@rhizomatics/signalk-einklabel-plugin 0.10.1 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+# 1.2.0
+
+- Added support for Gicisky labels (also known by other brands), tested with a 2.9" BWRY model
+- CLI render command use template height and width as defaults, can still be overridden by arguments to preview particular size of label
+- CLI paint commands use label height and width as defaults, overridden by arguments if needed
+- CLI paint command now has a `--reframe` option for labels that don't match template size, so can quickly test a label without having perfect template right away
+
+# 1.1.0
+
+- Label images can now optionally be emailed to an address every time they change, including a table of fields and values used to complete the template, or the prompt if genai based
+
+# 1.0.0
+
+## Full Release
+
+- The `1.0.0` reflects that this plugin has been working in real environment for months, and has been refactored for better extensibility
+
+## Extension Support
+
+- Custom templates and CLI commands can now be provided by a different plugin
+- Initially this is to support `signalk-einklabel-genai-plugin` which can use a prompt to make an image using a GenAI service like Anthropic or local Ollama
+
 # 0.10.1
 
 - Test fixes

package/README.md

@@ -6,8 +6,9 @@
 [![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)
 
-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.
+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.
 
 ![Companionway Tidal Clock](docs/assets/images/real_tidal_clock.jpg)
 
@@ -17,7 +18,7 @@ Electronic Shelf Labels are [eInk](https://en.wikipedia.org/wiki/E_Ink) devices
 
 Since they are designed to be used in large quantity in small shops, they are cheap and simple devices. Earlier models required dedicated controllers, or updates over Wifi or NFC, whereas many modern ones are standalone BLE devices that can be updated from a phone or server.
 
-Being battery operated, they can be stuck on anywhere without wiring - the only location constraints are bluetooth range, visibility (they need ambient light since the display is more like paper than a traditional lit-up electronic display) and out of the weather since the devices are intended for indoor use.
+Being battery operated, they can be stuck on anywhere without wiring - the only location constraints are bluetooth range, visibility (they need ambient light since the display is more like paper than a traditional lit-up electronic display) and, for some labels, being out of the weather if they are not waterproof, although IP65 labels are available.
 
 ## Pre-requisites
 
@@ -34,8 +35,9 @@ Most of requirements below are to make SignalK work with Bluetooth Low Energy, w
 
 - Bluetooth adapters for Linux can be tricky, TP-Link UB400 and Asus USB-BT500 are two well-known and available ones
 - Some Raspberry Pi models come with suitable Bluetooth built in
-- Don't worry about the very latest Bluetooth versions, 4.0 is minimum for BLE, 5.0 is nice
-- Home Assistant is massively more popular than SignalK, and often also run on Raspberry Pi and similar, so good source of advice
+
+> - Don't worry about the very latest Bluetooth versions, 4.0 is minimum for BLE, 5.0 is nice
+> - Home Assistant is massively more popular than SignalK, and often also run on Raspberry Pi and similar, so good source of advice
 
 3. `bluez` package installed in Linux
 
@@ -44,7 +46,7 @@ Most of requirements below are to make SignalK work with Bluetooth Low Energy, w
 
 4. One or more supported Electronic Shelf Labels
 
-- The label used for testing this is the [Zhsunyco 3.7" BWRY](https://www.aliexpress.com/item/1005010050104435.html)
+- The labels used for testing this are the [Zhsunyco 3.7" BWRY](https://www.aliexpress.com/item/1005010050104435.html) and a [Gicisky 2.9" BWRY](https://www.aliexpress.com/item/1005012933325056.html)
 
 5. Correct time zone set on server if local time is to be shown on display
 
@@ -113,7 +115,8 @@ Enable the plugin, and use the large **+** sign to add a label, which opens up t
 
 - _Friendly Name_ - Give the label any name (word or phrase) you like, for example 'Tide Clock'
 - _Device_ - Unless you have multiple labels, don't bother with pre-scanning or selecting a specific device, instead pick **"All discovered devices"** and it will paint any compatible labels it finds. If you want to pick a specific device, you'll need to wait for a device scan to complete.
-- _Template_ - Choose a built in template, or one you've added to the local templates directory
+- _Template_ - Choose a built-in template, one you've added to the local templates directory, or - if a companion plugin like [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) is installed - one of its own contributed entries (shown with a suffix, e.g. "forecast (GenAI)")
+- _Location/description_ - Optional free-text notes on where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m in poor light" - available to any template as `source=einklabel,path=description` or `source=label,path=description`
 - _Repaint Trigger_- Do you want this to repaint every few hours (at a chosen minutes past hour), or when a SignalK path changes?
   - If it's a SignalK path, enter it next, for example `environment.tide.state`
   - If it's time based, enter how many hours between repaints, for example 00:00/08:00/16:00 for an 8h schedule, and if you want a specific number of minutes after the hour.
@@ -146,6 +149,14 @@ Also known as 'Suny' and 'WOLink'.
 
 Python code for a variety of their labels at https://github.com/roxburghm/zhsunyco-esl and https://github.com/NickWaterton/Wolink
 
+### Gicisky
+
+Known by other names, e.g. 'Picksmart', and with white label brands
+
+- BLE ESLs
+  - Official store is on [AliExpress](https://www.aliexpress.com/store/911771479/pages/all-items.html?productGroupId=40000001654819&spm=a2g0o.store_pc_home.pcShopHead_6000727597996.1_1)
+  - Cheapest labels under £10 GBP / $13 USD
+
 ## Templating
 
 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.
@@ -207,6 +218,8 @@ Note that for dates and times, the server timezone must be set correctly, for ex
 
 Additionally, `round=n` can be used to round to limited decimal places.
 
+`default=<value>` substitutes `<value>` whenever the resolved value is missing (e.g. an unpublished path), instead of falling through to an empty string - useful anywhere a blank would be misread as a real answer. `default=` with nothing after the `=` still counts as set, deliberately defaulting to an empty string rather than leaving the fallback behaviour unchanged.
+
 These can all be combined as in `source=resources,resource=tides,provider=tides,path=extremes[2].level,category=depth,round=2`
 
 ### Non-Textual Fields (Images)
@@ -231,6 +244,16 @@ Three font types are loaded by default, use the generic font family, or exact fo
 - `sans-serif` - `Roboto`
 - `monospace` - `Roboto Mono`
 
+## GenAI Rendering
+
+As an alternative to hand-designed SVG templates, a device's content can be generated by an LLM instead - this is provided entirely by a separate companion plugin, [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin), not by this core plugin. The base plugin (BLE painting, SVG templates) has nothing to do with any LLM SDK or API key, so installing it never pulls in GenAI dependencies unless you also explicitly install and enable the companion plugin - the split is deliberate, for anyone on a small/constrained install or who'd simply rather not have any GenAI code in their install at all.
+
+Once the companion plugin is installed and enabled, its own config screen handles provider/model/API-key selection (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot AI, Ollama, or any other OpenAI-compatible endpoint), and its prompts show up as ordinary entries in this plugin's "Template" dropdown, suffixed (e.g. "forecast (GenAI)") - pick one exactly like you'd pick a `.svg` file. Under the hood it's a `TemplateProvider` (see [Extending](#extending) below) - the same extension mechanism a new vendor's hardware driver uses - so from this plugin's point of view it's just another way `templateName` gets resolved to an image.
+
+If the LLM call fails (network/API error, exhausted retries) or its response isn't renderable, this core plugin pushes its own bundled warning template instead of leaving the previous, possibly now-wrong, content on screen - so a stale weather prompt never quietly shows yesterday's forecast through today's storm. This is a generic safety net, not GenAI-specific: the exact same fallback covers a broken hand-authored template failing to render at all. The next scheduled repaint retries automatically. Since each repaint may call a (usually paid) LLM API, a GenAI-backed device should use Repaint Trigger `interval`, not `subscription`.
+
+See the companion plugin's own README for installing it, writing prompts, and its `esl-cli prompt`/`generate` commands for testing prompts without a device.
+
 ## Architecture
 
 The primary things managed and provided by the plugin are:
@@ -257,7 +280,17 @@ See also the commands useful for debugging under [Developing Templates]
 - `render` - transform an SVG template and data into a PNG
 - `paint` - render an SVG template and data to a selected ESL
 
-The width, height, vertical offset and colour palette for the device are taken from the internal register of devices, however can be overridden on the command line. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
+The width, height, vertical offset and colour palette for the device are taken from the internal register of devices, however can be overridden on the command line with `-w/--width`, `--height`, `--voffset` and `--colours`. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
+
+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:
+
+- `fixed` (default) - no adjustment; a size mismatch is rejected with an error, as it always has been
+- `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
+
+`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.
 
 ( The CLI can also be run from a checked out module, or by opening a terminal shell at `~/.signalk/node_modules/@rhizomatics/signalk-einklabel-plugin`, as `npx esl-cli command --args` )
 
@@ -278,7 +311,13 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 - `import esl from '@rhizomatics/signalk-einklabel-plugin'; esl.registerVendorDriver(myDriver)`
 - In the SignalK runtime, call this from the extension's own plugin `start()`. In the CLI, load the extension with `esl-cli --require <module> <command>`.
-- Declare this package as a `peerDependency` (not a regular dependency) in the extension package, so npm resolves a single shared copy of the registry.
+- Declare this package as a regular npm `dependency` in the extension package - **not** a `peerDependency`, per SignalK's own guidance 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 it.
+
+### 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`](#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.
+
+`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.
 
 ### Developing Templates
 
@@ -307,8 +346,40 @@ The `esl-cli` can be used to debug and validate templates quickly:
 - `fields` - List the fields in the template, with the source specification and the rendered data value
 - `field` - Accept a source specification (outside of any template context) and return the rendered value if available
 
+Use `--help` to get the full set of arguments for any of the commands.
+
 ### Examples
 
+#### Paint Image Directly
+
+The label address previously discovered via `esl-cli scan`
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93
+```
+
+If the label turns out to be a different size than the template (e.g. it's a 250x128 template on a 416x240 panel), that's normally rejected as a mismatch - add `--reframe` to fit it instead:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --reframe scale
+```
+
+#### Test Template Without Updating Label
+
+This will work even if you don't have a label, or even bluetooth. (The `-u` can be left out if your SignalK server running locally on default ports).
+
+```bash
+npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -u http://localhost
+```
+
+and this version will work even without a running SignalK server, using some pre-packaged example data:
+
+```bash
+npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -e examples
+```
+
+
+
 #### List all Fields and Rendered Values
 
 ```bash
@@ -380,7 +451,38 @@ If you have an SVG viewer extension, this will show the image rather than allowi
 
 Check if the text boxes are normal text or flowed text, and correct to normal text.
 
-## Other ESL and General eInk Resources
+### My label just shows "CONTENT UNAVAILABLE"
+
+That's the bundled fallback warning, not necessarily an error in this plugin - it means the most recent repaint failed, whatever produced the content (a broken hand-authored template, or a `TemplateProvider` extension like [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) - e.g. its LLM call failing on no network/API access, an invalid API key, or a response that wasn't a renderable SVG, after using up its configured retries). Check the SignalK server logs (debug logging on for this plugin) for the specific error, and if it's a GenAI device, check that plugin's own provider/API key/model settings. This plugin deliberately never leaves old content on screen when a repaint fails - it retries automatically at the next scheduled interval.
+
+### SignalK starts before the Bluetooth daemon — does the plugin need `bluetoothd` running at boot?
+
+The plugin retries BLE adapter initialisation with backoff (starting at 2s, capping at 30s) if `bluetoothd`/D-Bus isn't up yet when the plugin starts, so a slow-starting Bluetooth stack on boot will no longer strand it — it keeps retrying until the adapter appears rather than failing once and giving up. You'll see `BLE adapter not ready … — retrying in Ns …` in the SignalK logs in the meantime.
+
+That said, it's cleaner to fix the boot ordering at the systemd level so the plugin finds the adapter ready on its first attempt. If SignalK runs as a systemd service (`systemctl status signalk`) and its unit file has no `[Unit]` section (check with `systemctl cat signalk`), add one:
+
+```bash
+sudo systemctl edit signalk.service
+```
+
+This opens an override file — add:
+
+```ini
+[Unit]
+After=bluetooth.target
+Wants=bluetooth.target
+```
+
+Save and exit, then:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart signalk
+```
+
+This tells systemd to start `bluetoothd` first and wait for it before starting SignalK, rather than relying on both racing to start in parallel at boot.
+
+## Other ESL and General eInk Resources
 
 - [Open ePaper Link](https://openepaperlink.de) - Alternative open source firmware to flash onto eInk shelf labels, with Home Assistant integration.
 - [zhsunyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface

package/dist/cli/index.d.ts

@@ -1,2 +1,16 @@
 #!/usr/bin/env node
-export {};
+import { Command } from "commander";
+import { Colour } from "../devices/types";
+import { ReframeMode } from "../render/reframe";
+import { Binding } from "../render/binding";
+import { TemplateContext } from "../render/types";
+/** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
+export declare const DEFAULT_SIGNALK_URLS: string[];
+export declare function parseColours(code: string): Colour[];
+export declare function parseReframeMode(value: string): ReframeMode;
+/** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
+export declare function assembleContext(opts: {
+    url?: string;
+    exampleData?: string;
+}, bindings: Binding[]): Promise<TemplateContext>;
+export declare const program: Command;

package/dist/cli/index.js

@@ -1,12 +1,17 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.program = exports.DEFAULT_SIGNALK_URLS = void 0;
+exports.parseColours = parseColours;
+exports.parseReframeMode = parseReframeMode;
+exports.assembleContext = assembleContext;
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
 const commander_1 = require("commander");
 const xmldom_1 = require("@xmldom/xmldom");
 const registry_1 = require("../devices/registry");
 const zhsunyco_1 = require("../devices/zhsunyco");
+const gicisky_1 = require("../devices/gicisky");
 const bleDiscovery_1 = require("../devices/bleDiscovery");
 const svgRenderer_1 = require("../render/svgRenderer");
 const png_1 = require("../render/png");
@@ -17,9 +22,10 @@ const liveContext_1 = require("./liveContext");
 const httpJson_1 = require("../httpJson");
 const log_1 = require("./log");
 (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
+(0, registry_1.registerDriver)(new gicisky_1.GiciskyDriver());
 const VENDOR_IDENTIFY_TIMEOUT_MS = 30000;
 /** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
-const DEFAULT_SIGNALK_URLS = ["http://localhost", "http://localhost:3000", "https://localhost"];
+exports.DEFAULT_SIGNALK_URLS = ["http://localhost", "http://localhost:3000", "https://localhost"];
 const COLOUR_CODES = {
     BW: ["black", "white"],
     BWR: ["black", "white", "red"],
@@ -32,9 +38,16 @@ function parseColours(code) {
     }
     return colours;
 }
+const REFRAME_MODES = ["fixed", "scale", "crop"];
+function parseReframeMode(value) {
+    if (!REFRAME_MODES.includes(value)) {
+        throw new Error(`unknown --reframe value "${value}" - expected one of ${REFRAME_MODES.join(", ")}`);
+    }
+    return value;
+}
 /** Probes DEFAULT_SIGNALK_URLS in order and returns the first that answers a plain GET - used when -u/--url is omitted. */
 async function resolveDefaultUrl() {
-    for (const candidate of DEFAULT_SIGNALK_URLS) {
+    for (const candidate of exports.DEFAULT_SIGNALK_URLS) {
         try {
             (0, log_1.logDebug)(`probing ${candidate} as a default SignalK server`);
             await (0, httpJson_1.fetchJson)(`${candidate}/signalk`);
@@ -44,7 +57,15 @@ async function resolveDefaultUrl() {
             (0, log_1.logDebug)(`${candidate} did not answer: ${err.message}`);
         }
     }
-    throw new Error(`no -u/--url given and none of ${DEFAULT_SIGNALK_URLS.join(", ")} answered - specify the server explicitly with -u/--url`);
+    throw new Error(`no -u/--url given and none of ${exports.DEFAULT_SIGNALK_URLS.join(", ")} answered - specify the server explicitly with -u/--url`);
+}
+const DEFAULT_RENDER_WIDTH = 416;
+const DEFAULT_RENDER_HEIGHT = 240;
+/** Shared by every command's -w/--width and --height: an explicit flag always wins; otherwise the first defined value in `sources` (in order); otherwise a generic last-resort default. */
+function resolveDimension(explicit, sources, fallback) {
+    if (explicit !== undefined)
+        return Number(explicit);
+    return sources.find((value) => value !== undefined) ?? fallback;
 }
 /** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
 async function assembleContext(opts, bindings) {
@@ -73,21 +94,49 @@ async function identifyVendor(address) {
         destroy();
     }
 }
-const program = new commander_1.Command();
-program.name("esl-cli").description("Local CLI for testing ESL device scan and paint without a SignalK server");
-program.option("-r, --require <module>", "require a module before running, e.g. an npm package that registers a vendor driver (repeatable)", 
-// Commander's own typings declare `previous` as always `string[]`, but at runtime it's actually
-// `undefined` on the first invocation when no default is passed to `.option()` - the `| undefined`
-// here keeps that true and makes the `= []` fallback meaningful rather than dead code.
-(value, previous = []) => [...previous, value]);
-program.option("-l, --log-level <level>", "log verbosity: info or debug (e.g. trace which URLs are fetched)", "info");
-program.hook("preAction", () => {
-    (0, log_1.setLogLevel)(program.opts().logLevel);
-    for (const mod of program.opts().require ?? []) {
-        require(mod);
+/**
+ * Values passed via `-r`/`--require` (repeatable, `--require=value` form included), read directly from
+ * `process.argv` rather than through commander - see the doc comment below on why.
+ */
+function scanRequireModules(argv) {
+    const modules = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-r" || arg === "--require") {
+            if (argv[i + 1])
+                modules.push(argv[i + 1]);
+        }
+        else if (arg.startsWith("--require=")) {
+            modules.push(arg.slice("--require=".length));
+        }
     }
+    return modules;
+}
+// `program` is created (and exported) before anything is `require()`'d below, and before any built-in
+// `.command(...)` is defined - a `-r`'d extension module commonly `require()`s this same compiled file
+// (e.g. `require(".../dist/cli/index.js")`) to get at `program`/`assembleContext`/etc; since that's a
+// circular require back into the module currently being loaded, Node hands it back this module's
+// *exports object as it exists so far*, not the finished one - so `program` has to already be assigned
+// by this point, or the extension would see it as `undefined`.
+exports.program = new commander_1.Command();
+exports.program.name("esl-cli").description("Local CLI for testing ESL device scan and paint without a SignalK server");
+exports.program.option("-r, --require <module>", "require a module before running, e.g. an npm package that registers a vendor driver/template provider or contributes its own subcommands (repeatable) - loaded before any command is parsed", (value, previous = []) => [...previous, value]);
+exports.program.option("-l, --log-level <level>", "log verbosity: info or debug (e.g. trace which URLs are fetched)", "info");
+exports.program.hook("preAction", () => {
+    (0, log_1.setLogLevel)(exports.program.opts().logLevel);
 });
-program
+// Loaded here - after `program` exists (see above) but before any built-in `.command(...)` is defined,
+// and well before `.parseAsync()` at the bottom of this file - not in a commander `preAction` hook (as
+// this used to work), which only runs *after* commander has already resolved which command was invoked
+// and parsed its arguments. That timing is fine for a `-r`'d module that only registers a vendor driver
+// or template provider (an already-defined command's own action merely consults those registries when
+// it runs), but too late for one to contribute a brand-new *subcommand* (e.g. a companion plugin adding
+// its own `prompt`/`generate`) to this same invocation - by the time `preAction` fires, commander has
+// already decided there's no such command.
+for (const mod of scanRequireModules(process.argv)) {
+    require(mod);
+}
+exports.program
     .command("vendors")
     .description("List supported vendors and the device models each has confirmed metadata for")
     .action(() => {
@@ -114,10 +163,10 @@ program
     printRow(header);
     rows.forEach(printRow);
 });
-program
+exports.program
     .command("scan")
     .description("Scan for supported BLE ESL devices across all registered vendor drivers")
-    .option("-d, --duration <seconds>", "scan duration in seconds", "10")
+    .option("-d, --duration <seconds>", "scan duration in seconds", "30")
     .option("-a, --all-devices", "list every nearby BLE device, not just ones a registered driver recognised - unmatched devices show address/name/mfr/rssi only, since there's no driver to do a vendor-specific read like battery")
     .action(async (opts) => {
     const durationMs = Number(opts.duration) * 1000;
@@ -161,21 +210,22 @@ program
     printRow(header);
     rows.forEach(printRow);
 });
-program
+exports.program
     .command("paint")
     .description("Render a template against a live SignalK server and send it to a device")
     .option("-v, --vendor <vendor>", "vendor driver to use - if omitted, inferred from the device's advertised name")
     .requiredOption("-a, --address <address>", "BLE address of the device")
     .requiredOption("-t, --template <path>", "path to SVG template")
     .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .option("-k, --aes-key <hex>", "AES-128 key for device authentication, as 32 hex characters - defaults to the vendor's stock key if omitted")
-    .option("-w, --width <px>", "render width", "416")
-    .option("--height <px>", "render height", "240")
+    .option("-w, --width <px>", "render width - defaults to the template's declared width/viewBox - see --reframe for fitting onto a differently-sized panel")
+    .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("--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) => {
@@ -184,19 +234,30 @@ program
     if (!driver) {
         throw new Error(`no driver registered for vendor "${vendor}"`);
     }
+    const svgSource = await (0, promises_1.readFile)(opts.template, "utf-8");
+    // Defaults from the template's own declared size, same as `render` - not from the device's real
+    // panel size, which would need its own identify connect ahead of driver.paint()'s own connect;
+    // two back-to-back BLE connects on the same device is exactly the kind of churn that trips BlueZ
+    // (confirmed: identifyDevice() does a full connect+disconnect for zhsunyco, to read its PID off a
+    // GATT characteristic - immediately followed by paint()'s own connect crashed with a raw D-Bus
+    // "recipient disconnected from message bus without replying" on real hardware). --reframe below
+    // covers a mismatch against the real panel size within paint()'s own single connect instead.
+    const declared = (0, binding_1.readTemplateDimensions)(svgSource);
+    const width = resolveDimension(opts.width, [declared.width], DEFAULT_RENDER_WIDTH);
+    const height = resolveDimension(opts.height, [declared.height], DEFAULT_RENDER_HEIGHT);
     const modelOverride = opts.colours
         ? {
             label: "manual override",
-            width: Number(opts.width),
-            height: Number(opts.height),
+            width,
+            height,
             voffset: Number(opts.voffset),
             colours: parseColours(opts.colours),
         }
         : undefined;
-    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, "utf-8"));
+    const bindings = (0, binding_1.findBindings)(svgSource);
     const context = await assembleContext(opts, bindings);
     const renderer = new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height), (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
+    const bitmap = await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
     const connectTimeoutMs = Number(opts.connectTimeout) * 1000;
     await (0, bleDiscovery_1.withRetries)(Number(opts.retries), async (attempt) => {
         if (attempt > 1) {
@@ -207,38 +268,43 @@ program
             aesKey: opts.aesKey,
             modelOverride,
             connectTimeoutMs,
+            reframe: parseReframeMode(opts.reframe),
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
 });
-program
+exports.program
     .command("render")
     .description("Render a template against a live SignalK server and write a PNG, without needing a device")
     .requiredOption("-t, --template <path>", "path to SVG template")
     .requiredOption("-o, --output <path>", "output PNG path")
     .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
-    .option("-w, --width <px>", "render width", "416")
-    .option("--height <px>", "render height", "240")
+    .option("-w, --width <px>", "render width - defaults to the template's declared width/viewBox")
+    .option("--height <px>", "render height - defaults to the template's declared height/viewBox")
     .option("-f, --font <path>", "override a bundled font with this file (repeatable) - defaults to the bundled monospace/sans-serif/serif trio", 
 // See the -r/--require option above for why `| undefined` is needed here despite commander's typings.
 (value, previous = []) => [...previous, value])
     .action(async (opts) => {
-    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, "utf-8"));
+    const svgSource = await (0, promises_1.readFile)(opts.template, "utf-8");
+    const declared = (0, binding_1.readTemplateDimensions)(svgSource);
+    const width = resolveDimension(opts.width, [declared.width], DEFAULT_RENDER_WIDTH);
+    const height = resolveDimension(opts.height, [declared.height], DEFAULT_RENDER_HEIGHT);
+    const bindings = (0, binding_1.findBindings)(svgSource);
     const context = await assembleContext(opts, bindings);
     const renderer = opts.font ? new svgRenderer_1.SvgRenderer(opts.font) : new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height), (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
+    const bitmap = await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
     await (0, promises_1.writeFile)(opts.output, (0, png_1.bitmapToPng)(bitmap));
     console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})`);
 });
-program
+exports.program
     .command("fields")
     .description("List every <desc> binding in a template by element id, with its source spec and resolved value")
     .requiredOption("-t, --template <path>", "path to SVG template")
     .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .action(async (opts) => {
@@ -296,12 +362,12 @@ program
     printRow(header);
     table.forEach(printRow);
 });
-program
+exports.program
     .command("field")
     .description("Resolve a single binding spec directly against a live SignalK server, with no template")
     .argument("<spec>", 'binding spec, e.g. "source=resources,resource=tides,path=station.name" or a bare SignalK path')
     .option("-u, --url <url>", "SignalK server base URL - resolves the spec's source=signalk/resources binding - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .action(async (spec, opts) => {
@@ -309,7 +375,7 @@ program
     const context = await assembleContext(opts, [binding]);
     console.log((0, binding_1.renderBinding)(binding, context));
 });
-program.parseAsync(process.argv).catch((err) => {
+exports.program.parseAsync(process.argv).catch((err) => {
     console.error(err.message);
     process.exitCode = 1;
 });

package/dist/config.d.ts

@@ -17,6 +17,14 @@ export interface DeviceConfig {
      * live BLE read) and the BLE address, or the special value `ALL_DEVICES` (see above).
      */
     device: string;
+    /**
+     * Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table,
+     * viewed from ~1m in poor light" - purely descriptive. Available to any template via
+     * `source=einklabel,path=description` or `source=label,path=description` (see `buildLabelContext` in
+     * `./render/binding.ts`) if it wants it - e.g. useful to a `TemplateProvider` extension (see
+     * `./render/templateProviders.ts`) tailoring content to where the label actually sits.
+     */
+    description?: string;
     /** Per-device override; if omitted, the vendor driver may fall back to a stock/manufacturer-default key. */
     aesKey?: string;
     /**
@@ -25,8 +33,13 @@ export interface DeviceConfig {
      * (e.g. `templates/tides/416x240-BWRY.svg`) - `pickBestVariant` then picks whichever file inside it
      * best matches this entry's actual device(s), so one `DeviceConfig` (and one `ALL_DEVICES` entry in
      * particular) works across different panel sizes without the user picking a file for each.
+     *
+     * Can also name an entry a registered `TemplateProvider` offers (see `./render/templateProviders.ts`)
+     * instead of a file - e.g. `signalk-einklabel-genai-plugin` contributing `"forecast (GenAI)"` -
+     * `considerRepaint` (`./repaintScheduler.ts`) checks the provider registry before falling back to
+     * resolving this as a file path.
      */
-    templateName: string;
+    templateName?: string;
     repaintTrigger: "subscription" | "interval";
     /** SignalK path to subscribe to when `repaintTrigger` is `subscription` - a repaint is considered on every delta. */
     triggerPath?: string;
@@ -93,6 +106,18 @@ export interface PluginConfig {
  * `templates/.assets/lunar_phases`) just to keep a binding the override never touched working.
  */
 export declare const BUNDLED_TEMPLATES_DIR: string;
+/**
+ * Bundled template family pushed instead of a device's real content whenever a repaint fails - a broken
+ * hand-authored template, or a registered `TemplateProvider`'s `render()` rejecting (e.g.
+ * `@rhizomatics/signalk-einklabel-genai-plugin`'s LLM call failing) - see `considerRepaint` in
+ * `./repaintScheduler.ts`. Generic on purpose: it has no idea *why* the render failed, only that it
+ * did, and that the previous, possibly now-wrong, content must never be left on screen unmarked.
+ *
+ * Dot-prefixed like `.assets`/`.blank` so `listTemplateFamilies` excludes it from the "Template"
+ * dropdown - it's an internal fallback mechanism, not something a user should ever pick as a device's
+ * own template.
+ */
+export declare const RENDER_FALLBACK_TEMPLATE_NAME = ".error";
 export declare function defaultConfig(): PluginConfig;
 export declare function readCurrentConfig(app: ServerAPI): Partial<PluginConfig>;
 /**
@@ -106,12 +131,7 @@ export declare function readCurrentConfig(app: ServerAPI): Partial<PluginConfig>
  * flattened even if nothing ever triggers that path.
  */
 export declare function healNestedConfig(app: ServerAPI): void;
-/**
- * Resolves the user-facing `templatesDir` setting to an actual directory, mirroring
- * signalk-parquet's `outputDirectory` convention: empty means the default location, a relative
- * path is resolved against `~/.signalk` (where SignalK itself stores its config by default), and
- * an absolute path is used as-is.
- */
+/** See `resolveDir` - `templatesDir`'s own resolution. */
 export declare function resolveTemplatesDir(templatesDir: string | undefined): string;
 export declare function parseDevice(device: string): {
     vendor: string;