@rhizomatics/signalk-einklabel-plugin 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 1.3.1
+
+## 🐛 Bug fixes
+
+- Stopping the plugin mid-paint (saving its config, disabling it, or shutting down the server) now waits up to 30 seconds for that paint to finish, and starts no new paint or retry, so the restarted plugin no longer connects while the old Bluetooth session is still open
+
+## 📚 Documentation
+
+- Docs site made friendlier to AI coding agents: an [llms.txt](https://signalk-einklabel.rhizomatics.org.uk/llms.txt) index plus the whole documentation as Markdown in `llms-full.txt` and `llms-small.txt`, and every page available as Markdown by replacing its trailing `/` with `.md` (e.g. [getting-started.md](https://signalk-einklabel.rhizomatics.org.uk/getting-started.md))
+
 # 1.3.0
 
 ## BLE Manager

package/README.md

@@ -3,7 +3,6 @@
 [![npm version](https://img.shields.io/npm/v/@rhizomatics/signalk-einklabel-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-einklabel-plugin)
 [![npm downloads](https://img.shields.io/npm/dm/@rhizomatics/signalk-einklabel-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-einklabel-plugin)
 [![SignalK Plugin CI](https://github.com/rhizomatics/signalk-einklabel-plugin/actions/workflows/signalk-ci.yml/badge.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/actions/workflows/signalk-ci.yml)
-[![codecov](https://img.shields.io/codecov/c/github/rhizomatics/signalk-einklabel-plugin)](https://codecov.io/gh/rhizomatics/signalk-einklabel-plugin)
 [![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-blue.svg)](https://github.com)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/LICENSE)
 [![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)

package/dist/devices/bleDiscovery.d.ts

@@ -45,9 +45,15 @@ export declare function forEachAdvertisedDevice(adapter: Adapter, fn: (advertise
  * work can't be cancelled - this only lets the caller stop waiting for it.
  */
 export declare function withDeadline<T>(promise: Promise<T>, ms: number, what: string): Promise<T>;
-export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>, { delayMs, onError }?: {
+/**
+ * Runs `fn` up to `attempts` times, `delayMs` apart, rethrowing the last error if every attempt fails.
+ * `shouldStop` is checked after each failed attempt and again after the pause, so a plugin `stop()`
+ * ends the retry loop instead of opening a fresh BLE session behind the next `start()`.
+ */
+export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>, { delayMs, onError, shouldStop, }?: {
     delayMs?: number;
     onError?: (err: unknown, attempt: number) => void;
+    shouldStop?: () => boolean;
 }): Promise<T>;
 /**
  * Opens exactly one BLE discovery window and one D-Bus/BlueZ session, then hands the adapter to

package/dist/devices/bleDiscovery.js

@@ -92,7 +92,12 @@ async function withDeadline(promise, ms, what) {
         clearTimeout(timer);
     }
 }
-async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
+/**
+ * Runs `fn` up to `attempts` times, `delayMs` apart, rethrowing the last error if every attempt fails.
+ * `shouldStop` is checked after each failed attempt and again after the pause, so a plugin `stop()`
+ * ends the retry loop instead of opening a fresh BLE session behind the next `start()`.
+ */
+async function withRetries(attempts, fn, { delayMs = 0, onError, shouldStop = () => false, } = {}) {
     const total = Math.max(1, attempts);
     let lastErr;
     for (let attempt = 1; attempt <= total; attempt++) {
@@ -102,9 +107,11 @@ async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
         catch (err) {
             lastErr = err;
             onError?.(err, attempt);
-            if (attempt < total && delayMs > 0) {
+            if (attempt < total && delayMs > 0 && !shouldStop()) {
                 await sleep(delayMs);
             }
+            if (shouldStop())
+                break;
         }
     }
     throw lastErr;

package/dist/plugin.js

@@ -43,7 +43,11 @@ function createPlugin(app) {
     const bleApiAvailable = !!app.bleApi;
     let scheduler;
     let stopDiscoveryListener;
-    let stopped = false;
+    // Bumped by every start() and stop(), so a start() whose plugin has since been stopped (or
+    // restarted) can tell it's stale - a plain `stopped` flag would be reset by the next start().
+    let generation = 0;
+    // The last stop()'s drain of any in-flight repaint; start() waits on it before touching BLE.
+    let stopping = Promise.resolve();
     const plugin = {
         id: "signalk-einklabel-plugin",
         name: "eInk ESL (Electronic Shelf Label)",
@@ -60,14 +64,19 @@ function createPlugin(app) {
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
             (0, config_1.healStoredConfig)(app);
-            stopped = false;
+            const thisGeneration = ++generation;
+            const isCurrent = () => thisGeneration === generation;
+            const previousStop = stopping;
             const useBleApi = pluginConfig.useBleApi && bleApiAvailable;
             if (pluginConfig.useBleApi && !bleApiAvailable) {
                 app.debug("useBleApi is enabled but this SignalK server has no BLE Manager API (requires >= 2.32.0) - falling back to direct BlueZ access");
             }
             app.debug(useBleApi ? "using the SignalK BLE Manager API for Bluetooth access" : "using direct BlueZ access for Bluetooth");
-            const start = () => {
-                if (stopped)
+            const start = async () => {
+                // A server that doesn't await stop()'s Promise (or calls start() first) would otherwise have
+                // this connect while the previous session's paint is still running.
+                await previousStop;
+                if (!isCurrent())
                     return;
                 if (pluginConfig.scanOnStart) {
                     void runStartupScan(app, pluginConfig.scanDurationSeconds, useBleApi);
@@ -83,23 +92,27 @@ function createPlugin(app) {
                 // The server/provider governs its own local-adapter readiness once BLE Manager mode owns
                 // `hci0` (or has none at all, behind a remote gateway) - waiting on a *local* BlueZ adapter
                 // here would be waiting on something this mode may never even need.
-                start();
+                void start();
             }
             else {
                 // 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 again inside `start()`, not just passed
+                // boot-time race this covers. `isCurrent` is checked again inside `start()`, 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(start);
+                void (0, bleDiscovery_1.waitForAdapter)((message) => app.debug(message), () => !isCurrent()).then(start);
             }
         },
+        // Returns a Promise, as the server asks of a stop() with async work: it resolves once a paint
+        // already under way has finished (bounded by `STOP_DRAIN_TIMEOUT_MS`), so a config save mid-paint
+        // or a server shutdown doesn't leave that BLE session running behind the next start().
         stop() {
-            stopped = true;
-            scheduler?.stop();
+            generation++;
+            const stoppingScheduler = scheduler;
             scheduler = undefined;
             stopDiscoveryListener?.();
             stopDiscoveryListener = undefined;
-            app.debug("stopped");
+            stopping = (stoppingScheduler?.stop() ?? Promise.resolve()).then(() => app.debug("stopped"));
+            return stopping;
         },
     };
     return plugin;

package/dist/render/assets.js

@@ -19,7 +19,8 @@ function normalizeAssetKey(value) {
         .trim()
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "_")
-        .replace(/^_+|_+$/g, "");
+        // runs are already collapsed to a single `_` above, so one at each end is all there can be
+        .replace(/^_|_$/g, "");
     return normalized || undefined;
 }
 /**

package/dist/render/templateProviders.d.ts

@@ -51,6 +51,13 @@ export interface TemplateProvider {
      * screen unmarked.
      */
     render(request: TemplateRenderRequest): Promise<Bitmap>;
+    /**
+     * Optional, debug only: a human-readable description of what `render()` will be given for this
+     * request (e.g. a GenAI provider's prompt with every placeholder substituted) - `considerRepaint`
+     * writes it to `app.debug` just before calling `render()`, standing in for the `<desc>` bindings an
+     * SVG template's debug output would otherwise show. Throwing only skips that debug line, never the render.
+     */
+    describeContent?(request: TemplateRenderRequest): string;
 }
 export declare function registerTemplateProvider(provider: TemplateProvider): void;
 export declare function allTemplateProviders(): TemplateProvider[];

package/dist/repaintScheduler.d.ts

@@ -1,7 +1,18 @@
 import { ServerAPI } from "@signalk/server-api";
 import { PluginConfig } from "./config";
+/**
+ * How long `stop()` waits for a paint already in progress before resolving anyway. Long enough for a
+ * normal transfer to finish (so a config save mid-paint doesn't have the next `start()` connect while
+ * the old BLE session is still open), short enough not to hold up server shutdown on a label that's
+ * stuck; such a paint is still ended by its own connect timeout and `PAINT_ATTEMPT_BACKSTOP_MS`.
+ */
+export declare const STOP_DRAIN_TIMEOUT_MS = 30000;
 export interface RepaintScheduler {
-    stop(): void;
+    /**
+     * Stops every trigger, lets no new paint or retry start, and resolves once any paint already in
+     * progress finishes - or after `STOP_DRAIN_TIMEOUT_MS`, whichever comes first.
+     */
+    stop(): Promise<void>;
 }
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own
@@ -19,6 +30,15 @@ export declare function mostRecentScheduledSlot(now: Date, intervalHours: number
  * but only if it succeeded (`run` resolved `true`). For repaints: newer data still gets shown promptly,
  * but a label that's failing isn't hammered with a fresh round of retries straight after the last
  * one gave up - the next scheduled trigger tries again instead.
+ *
+ * `close()` makes every later call a no-op and drops pending follow-ups; `idle()` resolves once no
+ * `run` is in progress. Together they let the scheduler's `stop()` wait for a paint already under way
+ * without starting another.
  */
-export declare function oneAtATimePerKey<T>(keyOf: (arg: T) => string, run: (arg: T) => Promise<boolean>, onBusy?: (arg: T) => void): (arg: T) => Promise<void>;
+export interface OneAtATimePerKey<T> {
+    (arg: T): Promise<void>;
+    close(): void;
+    idle(): Promise<void>;
+}
+export declare function oneAtATimePerKey<T>(keyOf: (arg: T) => string, run: (arg: T) => Promise<boolean>, onBusy?: (arg: T) => void): OneAtATimePerKey<T>;
 export declare function startRepaintScheduler(app: ServerAPI, config: PluginConfig): RepaintScheduler;

package/dist/repaintScheduler.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_DRAIN_TIMEOUT_MS = void 0;
 exports.mostRecentScheduledSlot = mostRecentScheduledSlot;
 exports.oneAtATimePerKey = oneAtATimePerKey;
 exports.startRepaintScheduler = startRepaintScheduler;
@@ -33,6 +34,13 @@ const PAINT_RETRY_DELAY_MS = 5000;
  * the longest being the 5-minute GATT session watchdog in `bleBackend.ts`.
  */
 const PAINT_ATTEMPT_BACKSTOP_MS = 7 * 60000;
+/**
+ * How long `stop()` waits for a paint already in progress before resolving anyway. Long enough for a
+ * normal transfer to finish (so a config save mid-paint doesn't have the next `start()` connect while
+ * the old BLE session is still open), short enough not to hold up server shutdown on a label that's
+ * stuck; such a paint is still ended by its own connect timeout and `PAINT_ATTEMPT_BACKSTOP_MS`.
+ */
+exports.STOP_DRAIN_TIMEOUT_MS = 30000;
 const RESOURCES_API_PATH = "/signalk/v2/api/resources";
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own
@@ -248,7 +256,7 @@ async function resolveTargets(app, config, device) {
  * prompt showing "gentle breezes" through an actual storm), and not persisting a hash means the very
  * next scheduled tick retries for real rather than being suppressed by dedup.
  */
-async function considerRepaint(app, config, device, target, state, getApiUrl) {
+async function considerRepaint(app, config, device, target, state, getApiUrl, isStopping = () => false) {
     const { address, metadata, driver } = target;
     const label = `"${device.friendlyName}" [${address}]`;
     if (!device.templateName) {
@@ -334,8 +342,17 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
                 description: device.description ?? "",
             },
         };
+        const providerRequest = { templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours };
+        if (provider?.describeContent) {
+            try {
+                app.debug(`${label}: provider content:\n${provider.describeContent(providerRequest)}`);
+            }
+            catch (err) {
+                app.debug(`${label}: describeContent failed (${err.message})`);
+            }
+        }
         bitmap = provider
-            ? await provider.render({ templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours })
+            ? await provider.render(providerRequest)
             : await renderer.render(templatePath, renderContext, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
         succeeded = true;
         repaintReason = device.advanced?.forceRepaint
@@ -363,28 +380,35 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     const connectTimeoutMs = (device.advanced?.paintConnectTimeoutSeconds ?? config.paintConnectTimeoutSeconds) * 1000;
     const gattBackend = config.useBleApi && app.bleApi ? (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME) : undefined;
     const attempts = Math.max(1, device.advanced?.paintRetries ?? config.paintRetries);
-    const paintWithRetries = () => (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
-        app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
-        const startedAt = Date.now();
-        const paint = driver.paint(bitmap, {
-            address,
-            pid: target.pid,
-            aesKey: device.advanced?.aesKey,
-            connectTimeoutMs,
-            reframe: device.advanced?.reframe,
-            mirror: device.advanced?.mirror,
-            compress: device.advanced?.compress,
-            compressionFormat: device.advanced?.compressionFormat,
-            writeWithoutResponse: device.advanced?.writeWithoutResponse,
-            gattBackend,
-            log: (message) => app.debug(`${label}: ${message}`),
+    const paintWithRetries = () => {
+        // Rendering (or waiting for `exclusiveBleManagerAccess`) can outlast a `stop()` - don't open a
+        // BLE session for a plugin that's already stopping.
+        if (isStopping())
+            throw new Error("plugin stopping - paint skipped");
+        return (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
+            app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
+            const startedAt = Date.now();
+            const paint = driver.paint(bitmap, {
+                address,
+                pid: target.pid,
+                aesKey: device.advanced?.aesKey,
+                connectTimeoutMs,
+                reframe: device.advanced?.reframe,
+                mirror: device.advanced?.mirror,
+                compress: device.advanced?.compress,
+                compressionFormat: device.advanced?.compressionFormat,
+                writeWithoutResponse: device.advanced?.writeWithoutResponse,
+                gattBackend,
+                log: (message) => app.debug(`${label}: ${message}`),
+            });
+            await (0, bleDiscovery_1.withDeadline)(paint, connectTimeoutMs + PAINT_ATTEMPT_BACKSTOP_MS, `paint attempt ${attempt}/${attempts}`);
+            paintDurationMs = Date.now() - startedAt;
+        }, {
+            delayMs: PAINT_RETRY_DELAY_MS,
+            onError: (err, attempt) => app.debug(`${label}: paint attempt ${attempt}/${attempts} failed: ${err.message}`),
+            shouldStop: isStopping,
         });
-        await (0, bleDiscovery_1.withDeadline)(paint, connectTimeoutMs + PAINT_ATTEMPT_BACKSTOP_MS, `paint attempt ${attempt}/${attempts}`);
-        paintDurationMs = Date.now() - startedAt;
-    }, {
-        delayMs: PAINT_RETRY_DELAY_MS,
-        onError: (err, attempt) => app.debug(`${label}: paint attempt ${attempt}/${attempts} failed: ${err.message}`),
-    });
+    };
     await (gattBackend ? (0, bleBackend_1.exclusiveBleManagerAccess)(paintWithRetries) : paintWithRetries());
     (0, discoveredDevicesStore_1.touchDiscoveredDevice)(app, { address, vendor: target.vendor, pid: target.pid, hwVersion: target.hwVersion, metadata });
     // Only a successful render counts as "repainted" for dedup/catch-up purposes - a failure must not be
@@ -395,27 +419,24 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     }
     app.debug(succeeded ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)` : `${label}: repainted fallback warning`);
 }
-/**
- * Wraps `run` so only one call per key is in progress at a time. A call made while that key is busy
- * is folded into a single follow-up (with the latest arguments), run once the current one finishes -
- * but only if it succeeded (`run` resolved `true`). For repaints: newer data still gets shown promptly,
- * but a label that's failing isn't hammered with a fresh round of retries straight after the last
- * one gave up - the next scheduled trigger tries again instead.
- */
 function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
-    const inProgress = new Set();
+    const inProgress = new Map();
     const followUps = new Map();
+    let closed = false;
     const call = async (arg) => {
+        if (closed)
+            return;
         const key = keyOf(arg);
         if (inProgress.has(key)) {
             followUps.set(key, arg);
             onBusy(arg);
             return;
         }
-        inProgress.add(key);
+        const running = run(arg);
+        inProgress.set(key, running);
         let succeeded = false;
         try {
-            succeeded = await run(arg);
+            succeeded = await running;
         }
         finally {
             inProgress.delete(key);
@@ -426,12 +447,25 @@ function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
             await call(followUp);
         }
     };
-    return call;
+    return Object.assign(call, {
+        close() {
+            closed = true;
+            followUps.clear();
+        },
+        async idle() {
+            // A follow-up can start as an earlier run settles (unless closed), so loop until nothing is left.
+            while (inProgress.size > 0) {
+                await Promise.allSettled(inProgress.values());
+            }
+        },
+    });
 }
 function startRepaintScheduler(app, config) {
     const state = loadState(app);
     const unsubscribes = [];
     const getApiUrl = (0, resolveApiUrl_1.createApiUrlResolver)(config.signalkApiUrl);
+    let stopping = false;
+    const isStopping = () => stopping;
     // The first minute or two of a SignalK server's life is a chaos of plugin dependency sequencing -
     // a repaint attempted before other plugins (e.g. derived-data) have published the data a template
     // needs renders with missing/wrong values, and hash dedup (see `considerRepaint`) then means it
@@ -451,7 +485,7 @@ function startRepaintScheduler(app, config) {
         if (targets.length === 0) {
             return false;
         }
-        const results = await Promise.allSettled(targets.map((target) => considerRepaint(app, config, device, target, state, getApiUrl)));
+        const results = await Promise.allSettled(targets.map((target) => considerRepaint(app, config, device, target, state, getApiUrl, isStopping)));
         results.forEach((result, i) => {
             if (result.status === "rejected") {
                 app.debug(`"${device.friendlyName}" [${targets[i].address}]: repaint failed: ${result.reason.message}`);
@@ -525,9 +559,22 @@ function startRepaintScheduler(app, config) {
     }, settleMs);
     unsubscribes.push(() => clearTimeout(startupCheckTimer));
     return {
-        stop() {
+        async stop() {
+            stopping = true;
             for (const unsubscribe of unsubscribes)
                 unsubscribe();
+            repaint.close();
+            let timer;
+            const drained = await Promise.race([
+                repaint.idle().then(() => true),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(false), exports.STOP_DRAIN_TIMEOUT_MS);
+                }),
+            ]);
+            clearTimeout(timer);
+            if (!drained) {
+                app.debug(`a repaint was still running ${exports.STOP_DRAIN_TIMEOUT_MS / 1000}s after stop - not waiting any longer`);
+            }
         },
     };
 }

package/docs/bluetooth.md

@@ -30,7 +30,7 @@ First step is having a Bluetooth Low Energy (BLE) compatible bluetooth adapter a
 
 SignalK BLE Manager also supports BLE Gateways, which could be an MQTT topic or an ESP-32 device. The [espos-ble-gateway](https://github.com/dirkwa/espos-ble-gateway) can be used with a cheap ESP32 device (see the list of supported hardware), which allows positioning of the gateway closer to devices, or having multiple gateways on a big boat.
 
-## BLE Manager Readiness
+## BLE Manager Readiness
 
 v2.31.0 is the minumum version of SignalK possible for BLE Manager. Several fixes went in to v2.33.0 so this is the practical minimum version for using the plugin.
 
@@ -160,3 +160,32 @@ Following file created at /etc/tlp.d/99-bt500-no-autosuspend.conf
 ```
 USB_DENYLIST="0b05:190e"
 ```
+
+## Bluetooth Jargon Buster
+
+Bluetooth comes with a lot of acronyms. Here's what the ones on this page mean, without needing to be a computer person.
+
+When the plugin paints a label, the request goes down a chain: the plugin asks **BlueZ** over **D-Bus**, BlueZ gives orders to the Bluetooth dongle over **HCI**, and the dongle's radio talks to the label using **BLE**, reading and writing the label's **GATT** services. A **gateway** or **proxy** simply moves the radio end of that chain somewhere else on the boat.
+
+- **BLE (Bluetooth Low Energy)** - the kind of Bluetooth made for small battery-powered gadgets like labels, sensors and battery monitors.
+  - It's different from the "classic" Bluetooth used by headphones and speakers, and doesn't have the usual pairing process.
+  - BLE devices talk in short bursts and sleep in between, which is how a label runs for years on a coin cell.
+  - They regularly broadcast short "advertisements" saying who they are, and the server picks these up by _scanning_.
+  - BLE needs an adapter supporting Bluetooth 4.0 or later.
+- **HCI (Host Controller Interface)** - the standard set of commands a computer uses to give orders to a Bluetooth radio chip, such as "start scanning" or "connect to this device".
+  - Linux names each Bluetooth adapter after it, so `hci0` is the first adapter, `hci1` the second, and so on.
+  - A plugin using the adapter "directly" is sending HCI commands itself, works fine if there's only one Bluetooth app on the server.
+- **BlueZ** - the standard Bluetooth software on Linux.
+  - It runs quietly in the background as a service called `bluetoothd`, takes charge of the adapter, keeps a list of the devices it has heard, and handles connecting to them.
+  - Its a sane alternative to multiple Linux programs all trying to grab the limited resources of the Bluetooth adapter and stomping over each other. It does at a Linux level what BLE Manager does for SignalK - a single point of ownership and control over a contested resource.
+- **D-Bus** - the messaging system that programs on a Linux computer use to talk to each other.
+  - It's how the plugin, or SignalK's BLE Manager, asks BlueZ to scan or connect.
+  - If you know NMEA 2000, it's a similar idea: one shared backbone that everything plugs into and exchanges messages over, rather than a separate cable between every pair of devices.
+- **GATT (Generic Attribute Profile)** - how a BLE device organises what it offers once you're connected to it.
+  - The device has _services_, each a group of related features, and each service has _characteristics_, individual values you can read, write or be told about when they change.
+  - Painting a label means connecting, finding its image service, and writing the picture into the right characteristic a piece at a time.
+  - The "GATT claims" shown in SignalK's BLE Manager are simply which plugin has booked which device for a connection, so that two plugins don't try to talk to it at once.
+- **Gateway** - a separate small device, often a cheap ESP32 board, with its own Bluetooth radio, which listens for and talks to BLE devices near it and relays everything to SignalK over the boat's network.
+  - It's effectively fitting a remote antenna closer to where it's needed: useful when a label is too far from the server, or on a big boat that needs more than one. SignalK's BLE Manager can use gateways alongside, or instead of, a local adapter.
+- **Proxy** - much the same idea as a gateway: a device that does the Bluetooth radio work on the server's behalf, somewhere with a better signal.
+  - Different software uses different names for it. Home Assistant users, for example, will know ESP32 "Bluetooth proxies".

package/docs/design/roadmap.md

@@ -0,0 +1,9 @@
+# Design Plans
+
+## Label Support
+
+- More vendors, and more labels for existing vendors
+- Ability for people to plug-in vendor support for themselves or as published plugins
+- A model override in the plugin config, so a discovered device whose PID isn't in its driver's table yet can be repainted (the CLI's `paint --colours` already does this)
+- Neaps or springs status (e.g. "Springs +1", "Neaps -2") on the tide template, pending upstream signalk-tides support
+- Alternatives to SVG templates, perhaps [imagespec](https://pypi.org/project/imagespec/) or [signalk-hmi-designer](https://github.com/dirkwa/signalk-hmi-designer)

package/docs/design/spec.md

@@ -0,0 +1,59 @@
+# Design Specification
+
+A SignalK plugin, in TypeScript, that renders selected SignalK data to BLE eInk Electronic Shelf Labels (ESLs). This page describes the plugin as it is built. Plans and ideas not yet built are in the [roadmap](roadmap.md).
+
+# Features
+
+- Native TypeScript, Node 20 compatible (runs on armv7, e.g. a Cerbo GX)
+- Bundled templates for a tide clock and a watch schedule, rendered from any SignalK data, Resources API resource or label fact a template binds to
+- Pluggable vendor support
+  - Built-in drivers for Zhsunyco and Gicisky BLE labels (`src/devices/zhsunyco/`, `src/devices/gicisky/`), registered by `plugin.ts` at startup
+  - Each driver has a metadata table of the models it supports, keyed by PID, with `hwVersion` used where a vendor reuses a PID across panel sizes. Each entry gives the label, width, height, vertical offset and colours. `esl-cli vendors` lists them
+  - Additional vendors are added by a separate npm package implementing `VendorDriver` and calling the exported `registerVendorDriver` explicitly - no scanning of installed packages. In the SignalK runtime the extension calls it from its own plugin `start()`; the CLI loads it via `esl-cli --require <module>`. Extension packages declare this package as a regular `dependency`, not a `peerDependency` (SignalK's 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"] }` - see [Extending](../extending.md)
+  - The config schema's device and template options are read live from the registries when the schema is built, so a newly-registered extension shows up the next time the config panel is opened
+- Bluetooth access, either direct or shared
+  - Direct BlueZ access over D-Bus via `node-ble` (the default). The plugin waits, with backoff, for a local adapter before scanning or painting, to cover the boot-time race where the plugin starts before BlueZ is ready
+  - The SignalK BLE Manager API (`app.bleApi`, server >= 2.32.0), opted into with `useBleApi`, so the plugin shares the adapter with other BLE plugins. Only offered in the config schema when the running server has it. Paints through BLE Manager are serialised so only one label holds a GATT connection at a time
+- Device discovery
+  - One shared discovery path across all registered drivers (`discoveryCoordinator.ts`): each advertisement is read once and offered to each driver's `matchesAdvertisement`; only a matching driver's `identifyDevice` runs, which may open a GATT connection when the advertisement alone doesn't identify the model
+  - A scan already in progress is joined rather than a second one started, since neither backend can run two discovery sessions at once
+  - With direct BlueZ access, scanning happens in bounded windows: an optional startup scan (`scanOnStart`, off by default, `scanDurationSeconds` long), an on-demand scan when an "All discovered devices" entry has nothing discovered yet, or `esl-cli scan`. With BLE Manager, the plugin listens to its advertisement stream for as long as the plugin runs, and only identifies new addresses
+  - Discovered devices are persisted in the plugin data directory, keyed by BLE address, and kept for 24 hours after last being seen; a successful paint counts as being seen. The startup scan reports what it found in the plugin status line
+  - The device picker lists any device a driver identified as its vendor, even if the PID isn't in that driver's metadata table yet (labelled "vendor unrecognised PID 0x.... (address)"), so it can be reported. Such a device can't be repainted from the plugin, since there's no width/height to render with; `esl-cli paint` can paint one by supplying the model facts on the command line
+- Device configuration
+  - Each device entry has a friendly name, a combined "Device" choice, an optional location/description, a template and a repaint trigger, with less common settings grouped under "Advanced settings"
+  - The "Device" value is `"<vendor>:<pid>[:<hwVersion>]@<address>"`, picked from recently discovered devices, so width/height/colours are known from config alone and never need a live BLE read or a rescan after a restart. The special value `ALL` ("All discovered devices") paints the same template and trigger to every currently-known device instead, resolved at repaint time
+  - Advanced settings: reframe (`crop` by default, `scale`, or `fixed` to fail on a size mismatch), compress upload (on by default), mirror (`none`, `horizontal`, `vertical`, `both`), Gicisky wire format (`auto` or experimental `chunked`), Zhsunyco write-without-response, force repaint, Zhsunyco AES key (falls back to a default key), and per-device overrides of the plugin-wide paint connect timeout and retry count
+  - Config saved before advanced settings were grouped, or nested by an older save bug, is rewritten into the current shape at plugin start (`healStoredConfig`)
+- Templates
+  - SVG files, rendered to bitmaps with resvg-wasm (`src/render/svgRenderer.ts`). A user templates directory (`templatesDir`: empty for `~/.signalk/einklabel/templates`, relative to `~/.signalk`, or absolute) is scanned alongside the bundled `templates/` directory; a user template with the same name as a bundled one takes priority. There is no upload UI
+  - A template is either a single `.svg` file or a _template family_: a directory of variants named `<width>x<height>-<colours>.svg` (e.g. `tides/416x240-BWRY.svg`). The best variant for each device is picked at repaint time: exact size and colours, then exact size, then the nearest width with the closest aspect ratio. Dot-prefixed directories (`.assets`, `.blank`, `.error`) are never offered as templates
+  - Each template can be assigned to one or more devices. There is no separate data config; a template's own bindings declare what data it needs, re-read from the template on every repaint
+  - Text uses the bundled serif, sans-serif and monospace fonts (resvg-wasm can't see system fonts); the generic CSS family names are rewritten to the bundled fonts' exact names
+- Bindings
+  - A dynamic `<text>` element carries a flat `key=value,key=value` binding in a `<desc>` child, not a templating engine - e.g. `source=resources,resource=tides,path=extremes[0].time,format=local_time`. `source`/`context` default to `signalk`/`self`, a bare path with no `=` is shorthand for `path=...`, and array indices use bracket notation. The element's own text is a placeholder for laying out the template in an editor. See `src/render/binding.ts` for the grammar
+  - Keys: `source`, `context`, `resource`, `provider`, `path`, `format`, `category`, `round`, `assets`, `default`. An unknown key is an error; `default=` replaces a missing value
+  - `source=signalk` (default): `context=self` reads via `getSelfPath`; any other `context` is read via `getPath` against that literal SignalK context, exactly as shown in the Data Browser (e.g. `vessels.urn:mrn:imo:mmsi:232345678`)
+  - `source=resources`: `resource=<name>` reads any Resources API resource type (`tides`, `waypoints`, ...) via `app.resourcesApi.listResources` in-process. `provider=<plugin id>` pins it to one resource provider; a pinned binding goes over the REST API instead, since the in-process call ignores the provider id (signalk-server 2.30.0)
+  - `source=label`: facts about the physical label - `manufacturer`, `label`, `width`, `height`, `colours`, `fonts`, `description`, and `position` (rounded to about 1km so GPS jitter doesn't force repaints)
+  - `source=einklabel`: plugin-injected values - `repainted` (repaint time), `local_zone` (timezone abbreviation) and `plugin_version`
+  - `format=` names a formatter from `src/render/formatters.ts`: `local_time`, `day_mon`, `local_datetime_short`, `utc_offset`, `position`, `csv`. Times use the vessel's `environment.time.timezoneRegion` when published, otherwise the host's timezone - never a tide station's own `timezone` field
+  - A `signalk`-sourced numeric value converts to its path's preferred display unit by default, via `GET {signalkApiUrl}/signalk/v1/api/vessels/<context>/meta` (there's no in-process equivalent); `format=raw` opts out. A value with no path of its own (e.g. resource-sourced) can take an explicit `category=<name>` (e.g. `category=depth`), resolved from `{signalkApiUrl}/signalk/v1/unitpreferences/...` client-side (`src/unitCategories.ts`). `round=` sets decimal places
+  - An `<image>` element with a `<desc>` binding and an `assets=<name>` key picks one `.svg` from an asset directory (`.assets/<name>/`, user templates directory first, then bundled) by the resolved value, e.g. the bundled `lunar_phases` icons for `environment.moon.phaseName`. The element is dropped when the value is missing or has no matching file
+- SignalK API base URL
+  - `signalkApiUrl` is optional. Left unset, `resolveSignalkApiUrl` (`src/resolveApiUrl.ts`) probes `http://localhost:3000`, `http://localhost` and `https://localhost`, in that order, at the first repaint and caches whichever responds. Always the loopback address, since the plugin runs on the same host as the server. Setting it explicitly skips probing but is still verified
+  - It errors clearly if nothing responds (wrong port) or every probe is rejected (anonymous read access not enabled) - these endpoints need anonymous read access, since the plugin has no login flow. A failed resolution is retried on the next repaint rather than cached
+  - Path metadata is best-effort (no server just means raw values); a `category=` or `provider=` binding without a reachable server fails the render
+- Repainting
+  - Each device picks one repaint trigger: a change on a SignalK path (`subscription`, debounced by 2 seconds, ignoring transient null/missing values), or a fixed interval (every N hours at a configurable minute past the hour, checked by one shared one-minute timer rather than one per device)
+  - Every trigger waits for a settle window after plugin start (`settleSeconds`, default 120), so a template isn't rendered before other plugins (e.g. derived-data) have published its data. After that window each device is checked once; an interval device already painted for its current slot skips this catch-up
+  - Before repainting, the template's mtime and the assembled data (bindings plus label facts, before plugin-injected values like the repaint time are added) are hashed and compared against the last successful paint, persisted in the plugin data directory per device entry and BLE address (`friendlyName:address`). If both are unchanged the repaint is skipped, to save the label's battery and avoid a full-panel flash. A template provider's output always repaints, since the plugin can't know whether it would differ
+  - "Force repaint" bypasses the unchanged-data skip for one repaint, then clears itself once every target device has painted successfully
+  - Only one repaint per device entry runs at a time; a trigger arriving mid-repaint queues one follow-up, run only if the current repaint succeeded
+  - A paint is retried up to `paintRetries` times (default 3, 5 seconds apart), each attempt bounded by `paintConnectTimeoutSeconds` (default 30) plus a backstop deadline
+  - Stopping the plugin (a config save, disable, or server shutdown) stops every trigger, drops queued follow-ups and retries, and skips a paint that hasn't connected yet. `stop()` returns a Promise that resolves once a paint already under way has finished, waiting at most 30 seconds, and the next `start()` also waits for it, so two BLE sessions don't overlap
+  - If rendering fails (a broken template, a missing file, or a template provider's `render()` rejecting), the bundled `.error` warning template is painted instead, so stale content is never left on screen unmarked. No success hash is saved, so the next trigger retries
+- Template providers
+  - An extension package can offer content generated another way, alongside SVG templates, via `registerTemplateProvider` - e.g. `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt. Its entries appear in the same "Template" dropdown, marked by the provider's `suffix`. See [Extending](../extending.md) and `src/render/templateProviders.ts`
+- `esl-cli`, a local CLI for scanning, painting and testing templates outside the SignalK plugin
+  - `vendors`, `scan`, `paint` (with the same image options as the plugin, plus `--colours`/`--width`/`--height`/`--voffset` model facts for hardware not yet in a driver's table), `render` (template to PNG), `fields` (every binding in a template with its resolved value) and `field` (one binding spec). Bindings resolve against a live SignalK server over HTTP, or against local example JSON (`-e examples`). Extensions can add subcommands via `--require`. See [Command Line Interface](../cli.md)

package/docs/extending.md

@@ -24,9 +24,9 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 ## Template Providers
 
-An alternative way to produce a device's content, alongside hand-authored SVG templates, can be added the same way - `esl.registerTemplateProvider({ suffix, listTemplates, render })`, from a separate package's own plugin `start()` (or `esl-cli --require <module>`). This is what [`@rhizomatics/signalk-einklabel-genai-plugin`](templates.md#genai-rendering) is: `listTemplates()` returns the entries it currently offers (already including its own `suffix`, e.g. `"forecast (GenAI)"`) for the "Template" dropdown, and `render(request)` - given the same signalk/resources/label context any SVG template's bindings get - returns a `Bitmap`, exactly as `SvgRenderer.render()` would. Rejecting from `render()` routes the repaint through this plugin's own generic fallback-warning template, the same as a broken hand-authored template failing to render.
+An alternative way to produce a device's content, alongside hand-authored SVG templates, can be added the same way - `esl.registerTemplateProvider({ suffix, listTemplates, render })`, from a separate package's own plugin `start()` (or `esl-cli --require <module>`). This is what [`@rhizomatics/signalk-einklabel-genai-plugin`](templates.md#genai-rendering) is: `listTemplates()` returns the entries it currently offers (already including its own `suffix`, e.g. `"forecast (GenAI)"`) for the "Template" dropdown, and `render(request)` - given the same signalk/resources/label context any SVG template's bindings get - returns a `Bitmap`, exactly as `new esl.Renderer().render()` would for an SVG template. Rejecting from `render()` routes the repaint through this plugin's own generic fallback-warning template, the same as a broken hand-authored template failing to render. An optional `describeContent(request)` returns a human-readable description of what `render()` will be given (the GenAI plugin returns its fully-substituted LLM prompt); when present, it's logged to the plugin's debug output just before each `render()`, standing in for the `<desc>` bindings an SVG template's debug output would show.
 
-`esl.SvgRenderer`, `esl.buildLabel`, `esl.findBindingsInText`, and `esl.substituteBindingsInText` are also exported for a `TemplateProvider` extension to reuse - e.g. to resolve its own `{...}`-style placeholders against the request's context, or to rasterize whatever SVG it produces into the `Bitmap` its `render()` must return.
+`esl.Renderer` (the SVG renderer), `esl.bitmapToPng`, `esl.buildLabel`, `esl.findBindingsInText`, and `esl.substituteBindingsInText` are also exported for a `TemplateProvider` extension to reuse - e.g. to resolve its own `{...}`-style placeholders against the request's context, or to rasterize whatever SVG it produces into the `Bitmap` its `render()` must return.
 
 ## CLI Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",
@@ -76,14 +76,15 @@
     "@types/luxon": "^3.7.5",
     "@types/node": "^26.6.0",
     "@types/pngjs": "^6.0.5",
-    "oxfmt": "^0.70.0",
+    "oxfmt": "^0.74.0",
     "oxlint": "^1.85.0",
     "oxlint-tsgolint": "^7.0.2001",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22",
+    "signalk-server": ">=2.25.0"
   },
   "signalk": {
     "displayName": "eInk Label Displays",