@rhizomatics/signalk-einklabel-plugin 0.8.1 → 0.9.0-beta1

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# 0.9.0
+
+- Rename `third_quarter` to `last_quarter` for moon phase icons in `templates/.assets/lunar_phases` to match Derived Data plugin
+- `tide.svg` renamed to `tides\416x240-BWRY.svg`. Original maintained but labelled as deprecated
+- Added a simpler 250x128 version of tide clock for 2.13" labels
+- Fix configuration JSON holding older versions of itself as subentries
+- Repaint state used to track which labels to repaint separately tracks the template and data changes
+- Fix most cases of scanned devices not appearing in device dropdown choice
+- `nearestColour` algorithm in Zhsunyco driver supports ESLs that only have BWR or BW
+- New 'ALL' as device option, and by default disable initial scan, to optimize support for single devices
+  - Scan and explicit device selection only required then for boats with multiple devices
+- Now support a directory of templates, where each is named like `416-240-BWRY.svg` to support same functions on different devices.
+- Picks the template within the directory that most closely matches the tide clock height/width/colour-set, if not matched then height/width, and then best h/w ratio for nearest width
+- `template/assets` is now `template/.assets`
+
+# 0.8.2
+
+- Work around a SignalK bug in Server API where `ResourcesApi.listResources()` merges provider values in undetermined order and ignores specified provider.
+
 # 0.8.1
 
 - A preferred `provider` can now be set for `resources`.

package/README.md

@@ -89,7 +89,11 @@ Since these are ultra-low power devices, they don't respond instantly to either
 
 One other quirk is that some devices respond with a different name at different times, for example the genric `WOESL` sometimes and model specific `WL17500C74` other times. However, the MAC address, e.g. `66:66:17:50:0D:2B` is constant, and this is what's tracked by the plugin.
 
-The plugin will optionally re-scan whenever it starts up, although this isn't essential once a label has been configured.
+The plugin can optionally re-scan whenever it starts up (off by default), although this isn't essential once a label has been configured. Devices found by any scan are remembered across restarts - see the FAQ below.
+
+#### Selecting a Device
+
+A device's "Device" field can either be a specific device picked from the scan dropdown, or **"All discovered devices"**, which paints that same template/trigger to every device the plugin currently knows about. This is the simplest option for a boat with just one label - there's no need to scan first and pick it out, and if nothing's been discovered yet, selecting it triggers a scan itself the first time it's needed. It also covers several identical labels with one config entry, without listing each one out.
 
 ### Scheduling
 
@@ -107,6 +111,16 @@ The devices will be painted when the plugin starts, and then every time the sele
 
 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.
 
+### Template Families (multiple panel sizes/colours)
+
+A "Template" selection can either be one specific `.svg` file, or a _directory_ holding several same-purpose templates 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. Each file is named `<width>x<height>-<colours>.svg`, where `<colours>` is one letter per supported colour: `B`(lack)/`W`(hite)/`R`(ed)/`Y`(ellow) - e.g. `BWRY` for a 4-colour panel, `BWR` for a 3-colour one.
+
+Selecting the directory (e.g. `tides`) instead of one file lets one `DeviceConfig` entry - especially a `device: "All discovered devices"` entry covering several different physical panels - automatically pick the best-fitting file for each device's actual size/colours, trying in order:
+
+1. An exact width/height/colour-set match.
+2. Failing that, width/height alone (any colour-set).
+3. Failing that too, the nearest width, tie-broken by whichever file's own height/width ratio is closest to the device's.
+
 ### Template Source Specification
 
 In the `description` of the SVG text box, use a comma separated set of key value pairs to define the data source and formatting.
@@ -156,17 +170,17 @@ These can all be combined as in `source=resources,resource=tides,provider=tides,
 
 ### Non-Textual Fields (Images)
 
-The same `<desc>` mechanism works on an `<image>` element instead of a `<text>` element, for a value that's better shown as a picture than as text - a moon phase icon, a wind direction arrow, a weather condition glyph, and so on. Rather than substituting text, the resolved value picks one of a directory of `.svg` files to embed, by an extra required `assets=` key naming that directory - an `assets/<name>` sub-directory looked up in your configured `templates` directory first, and the bundled `templates` directory otherwise. For example, the tide clock's moon phase icon uses:
+The same `<desc>` mechanism works on an `<image>` element instead of a `<text>` element, for a value that's better shown as a picture than as text - a moon phase icon, a wind direction arrow, a weather condition glyph, and so on. Rather than substituting text, the resolved value picks one of a directory of `.svg` files to embed, by an extra required `assets=` key naming that directory - an `.assets/<name>` sub-directory looked up in your configured `templates` directory first, and the bundled `templates` directory otherwise. For example, the tide clock's moon phase icon uses:
 
 ```
 path=environment.moon.phaseName,assets=lunar_phases
 ```
 
-which resolves against `templates/assets/lunar_phases/` (bundled, or your own configured `templates` directory's `assets/lunar_phases/` if you have one). The resolved value (e.g. `"Waning Gibbous"`, as published by the [derived-data](https://www.npmjs.com/package/signalk-derived-data) plugin) is normalized to match a filename - lower-cased, punctuation and spaces collapsed to underscores - so `"Waning Gibbous"` picks `waning_gibbous.svg` out of that directory. If the underlying path has no value at all (e.g. the `derived-data` plugin isn't installed), or the value doesn't normalize to any file in the directory, the `<image>` element is omitted from that render - no broken image, no placeholder, nothing shown - and a line is logged to the console so a missing/unmatched value isn't silently invisible.
+which resolves against `templates/.assets/lunar_phases/` (bundled, or your own configured `templates` directory's `.assets/lunar_phases/` if you have one). The resolved value (e.g. `"Waning Gibbous"`, as published by the [derived-data](https://www.npmjs.com/package/signalk-derived-data) plugin) is normalized to match a filename - lower-cased, punctuation and spaces collapsed to underscores - so `"Waning Gibbous"` picks `waning_gibbous.svg` out of that directory. If the underlying path has no value at all (e.g. the `derived-data` plugin isn't installed), or the value doesn't normalize to any file in the directory, the `<image>` element is omitted from that render - no broken image, no placeholder, nothing shown - and a line is logged to the console so a missing/unmatched value isn't silently invisible.
 
-If you don't like the bundled moon phase icons, save your own `<value>.svg` files in the `assets/lunar_phases` sub-directory of your configured `templates` directory - the whole directory is used in place of the bundled one, so add all 8 phases you want to keep, not just the ones you're changing.
+If you don't like the bundled moon phase icons, save your own `<value>.svg` files in the `.assets/lunar_phases` sub-directory of your configured `templates` directory - the whole directory is used in place of the bundled one, so add all 8 phases you want to keep, not just the ones you're changing.
 
-This is a general mechanism, not specific to moon phases - any `source`/`context`/`path`/`format` combination valid for a `<text>` binding works here too (a `source=resources` value, an explicit `category=`, etc.), the only difference is the required `assets=` directory and the "no match -> no image" behaviour instead of substituted text. To add your own, put a directory of `<value>.svg` files under an `assets/<name>` sub-directory of your `templates` directory, add an `<image>` element in your SVG editor at the size/position you want, and give it a `<desc>` the same way you would a text field - overriding just the template, just its assets, or both together, all work independently.
+This is a general mechanism, not specific to moon phases - any `source`/`context`/`path`/`format` combination valid for a `<text>` binding works here too (a `source=resources` value, an explicit `category=`, etc.), the only difference is the required `assets=` directory and the "no match -> no image" behaviour instead of substituted text. To add your own, put a directory of `<value>.svg` files under an `.assets/<name>` sub-directory of your `templates` directory, add an `<image>` element in your SVG editor at the size/position you want, and give it a `<desc>` the same way you would a text field - overriding just the template, just its assets, or both together, all work independently.
 
 ### Fonts
 
@@ -305,6 +319,10 @@ For example, `npx esl-cli fields -t templates/tide.svg -e examples` will show al
 
 ## Frequently Asked Questions
 
+### I can't see my device as a choice on the drop-down list after scan
+
+SignalK plugins lack ability to self-update after something like a scan, so first time round you may have to close the config and reload it to see this. Subsequently the plugin will remember all scanned devices, and only drop previously seen ones if it goes 24 hours without a positive scan or with failed paint attempts.
+
 ### Sometimes values are missing on the display
 
 If the plugin repaints a display at server startup, then the plugin that provides the data may not have started ( or in the case of `derived-data` the plugin that the plugin depends on! ) and unlike Home Assistant, there's no good way of sequencing the start of plugins.
@@ -322,9 +340,15 @@ If you're a global cruiser, then use something like [signalk-set-gps-timezone](h
 
 Try a BLE proxy device, ESP32 is popular for this.
 
+### Can't edit the text contents of SVG template in VSCode
+
+If you have an SVG viewer extension, this wll show the image rather than allowing editing of text. To solve, right click on the file in VSCode _Explorer_ view and choose to edit with _Text Editor_.
+
 ## 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.
+- [zhsynyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface
+- [WoLink](https://github.com/NickWaterton/Wolink) - Python interface and protocol analysis
 - [e-ink dashboard for Signal K](https://github.com/meri-imperiumi/dashboard) - Waveshare display based multi instrument display.
 - [eInk Dashboard Modern SK](https://github.com/VladimirKalachikhin/e-inkDashboardModernSK) - SignalK dashboard for non-ESL eInk display.
 - [esp32-esl-system](https://github.com/giobauermeister/esp32-esl-system) - Docker and ESP32 based system for updating ESLs.

package/dist/config.d.ts

@@ -1,15 +1,31 @@
 import { ServerAPI } from "@signalk/server-api";
-import { DiscoveredDevice } from "./devices/types";
+import { Colour, DiscoveredDevice } from "./devices/types";
+/**
+ * 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
+ * physical label without picking each one out of the scan dropdown individually, e.g. several
+ * identical labels on a boat, or just to skip the scan-then-select step for the common single-label
+ * case. Resolved lazily at repaint time (see `resolveTargets` in `repaintScheduler.ts`), triggering
+ * an on-demand scan itself if nothing's been discovered yet.
+ */
+export declare const ALL_DEVICES = "ALL";
 export interface DeviceConfig {
     friendlyName: string;
     /**
-     * `"<vendor>:<pid>[:<hwVersion>]@<address>"`, picked from a combined enum of recently
-     * scanned devices so one selection sets both the model (width/height/colours, known
-     * without a live BLE read) and the BLE address.
+     * Either `"<vendor>:<pid>[:<hwVersion>]@<address>"`, picked from a combined enum of recently
+     * scanned devices so one selection sets both the model (width/height/colours, known without a
+     * live BLE read) and the BLE address, or the special value `ALL_DEVICES` (see above).
      */
     device: string;
     /** Per-device override; if omitted, the vendor driver may fall back to a stock/manufacturer-default key. */
     aesKey?: string;
+    /**
+     * Either one specific `.svg` file, or the name of a *template-family* directory holding several
+     * same-purpose templates for different panel sizes/colour-sets, named `<width>x<height>-<colours>.svg`
+     * (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.
+     */
     templateName: string;
     repaintTrigger: "subscription" | "interval";
     /** SignalK path to subscribe to when `repaintTrigger` is `subscription` - a repaint is considered on every delta. */
@@ -28,7 +44,12 @@ export interface PluginConfig {
      * `~/.signalk`, or an absolute path. Use `resolveTemplatesDir` to turn this into an actual path.
      */
     templatesDir: string;
-    /** Run a short BLE scan on plugin start and report discoveries via plugin status, like signalk-bluetti-plugin does. */
+    /**
+     * Run a short BLE scan on plugin start and report discoveries via plugin status, like
+     * signalk-bluetti-plugin does. Off by default - a `device: ALL_DEVICES` entry scans on demand the
+     * first time it has nothing discovered yet (see `resolveTargets` in `repaintScheduler.ts`), and an
+     * explicit device selection only ever needed this to populate the dropdown once at initial setup.
+     */
     scanOnStart: boolean;
     /** How long the startup scan runs, in seconds. */
     scanDurationSeconds: number;
@@ -69,10 +90,23 @@ export interface PluginConfig {
  * user's `templatesDir` takes priority. Exported so `SvgRenderer` can fall back to it when resolving
  * an `assets=` binding's directory (see `resolveAssetPath` in `./render/assets.ts`) - overriding a
  * bundled template shouldn't also require duplicating its bundled asset sets (e.g.
- * `templates/assets/lunar_phases`) just to keep a binding the override never touched working.
+ * `templates/.assets/lunar_phases`) just to keep a binding the override never touched working.
  */
 export declare const BUNDLED_TEMPLATES_DIR: string;
 export declare function defaultConfig(): PluginConfig;
+/**
+ * `app.readPluginOptions()`/`savePluginOptions()` aren't actually symmetric despite what their doc
+ * comments imply: signalk-server's `readPluginOptions()` returns the *whole* on-disk file
+ * (`{ configuration, enabled, enableDebug, enableLogging }`), not just the `configuration` object
+ * `savePluginOptions()` writes into - see signalk-server's `interfaces/plugins.ts`
+ * (`appCopy.readPluginOptions = () => getPluginOptions(plugin.id)` vs.
+ * `appCopy.savePluginOptions = (configuration, cb) => savePluginOptions(id, { ...getPluginOptions(id), configuration }, cb)`).
+ * Spreading that return value straight back into a save call therefore nests the whole file one level
+ * deeper inside its own `configuration` key every time (see `support/signalk-einklabel-plugin.json` and
+ * `clearForceRepaint` in `./repaintScheduler.ts`). Unwrapping any such nesting and keeping only recognised
+ * fields here means every save collapses back down instead of growing, self-healing an already-corrupted file.
+ */
+export declare function readCurrentConfig(app: ServerAPI): Partial<PluginConfig>;
 /**
  * Resolves the user-facing `templatesDir` setting to an actual directory, mirroring
  * signalk-parquet's `outputDirectory` convention: empty means the default location, a relative
@@ -86,7 +120,17 @@ export declare function parseDevice(device: string): {
     hwVersion?: string;
     address: string;
 } | undefined;
-/** Resolves a template name to an actual file path - a local template overrides the bundled one of the same name. */
-export declare function resolveTemplatePath(templatesDir: string, templateName: string): string;
+/**
+ * Resolves a template name to an actual file path - a local template overrides the bundled one of the
+ * same name. `templateName` can also name a template-family *directory* (see `pickBestVariant`), in
+ * which case `target` (the device's actual width/height/colours) picks the best file inside it. A
+ * `target`-less call, or one where `templateName` just isn't a directory, falls through to the plain
+ * flat-file behaviour - the only kind the CLI (which always names an exact file) ever uses.
+ */
+export declare function resolveTemplatePath(templatesDir: string, templateName: string, target?: {
+    width: number;
+    height: number;
+    colours: Colour[];
+}): string;
 export declare function configSchema(app: ServerAPI, discovered?: DiscoveredDevice[]): object;
 export declare function configUiSchema(): object;

package/dist/config.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUNDLED_TEMPLATES_DIR = void 0;
+exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
 exports.defaultConfig = defaultConfig;
+exports.readCurrentConfig = readCurrentConfig;
 exports.resolveTemplatesDir = resolveTemplatesDir;
 exports.parseDevice = parseDevice;
 exports.resolveTemplatePath = resolveTemplatePath;
@@ -11,13 +12,22 @@ const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
 const resolveApiUrl_1 = require("./resolveApiUrl");
+/**
+ * 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
+ * physical label without picking each one out of the scan dropdown individually, e.g. several
+ * identical labels on a boat, or just to skip the scan-then-select step for the common single-label
+ * case. Resolved lazily at repaint time (see `resolveTargets` in `repaintScheduler.ts`), triggering
+ * an on-demand scan itself if nothing's been discovered yet.
+ */
+exports.ALL_DEVICES = "ALL";
 /**
  * The package's own bundled `templates/` directory (ships alongside `dist/`, see
  * package.json's `files`) - templates here are always available, but a same-named template in the
  * user's `templatesDir` takes priority. Exported so `SvgRenderer` can fall back to it when resolving
  * an `assets=` binding's directory (see `resolveAssetPath` in `./render/assets.ts`) - overriding a
  * bundled template shouldn't also require duplicating its bundled asset sets (e.g.
- * `templates/assets/lunar_phases`) just to keep a binding the override never touched working.
+ * `templates/.assets/lunar_phases`) just to keep a binding the override never touched working.
  */
 exports.BUNDLED_TEMPLATES_DIR = (0, path_1.join)(__dirname, "..", "templates");
 const SIGNALK_HOME_DIR = (0, path_1.join)((0, os_1.homedir)(), ".signalk");
@@ -25,7 +35,7 @@ const DEFAULT_TEMPLATES_DIR = (0, path_1.join)(SIGNALK_HOME_DIR, "einklabel", "t
 function defaultConfig() {
     return {
         templatesDir: "",
-        scanOnStart: true,
+        scanOnStart: false,
         scanDurationSeconds: 20,
         paintConnectTimeoutSeconds: 30,
         paintRetries: 3,
@@ -33,6 +43,46 @@ function defaultConfig() {
         devices: [],
     };
 }
+const PLUGIN_CONFIG_KEYS = [
+    "templatesDir",
+    "scanOnStart",
+    "scanDurationSeconds",
+    "paintConnectTimeoutSeconds",
+    "paintRetries",
+    "settleSeconds",
+    "signalkApiUrl",
+    "devices",
+];
+/**
+ * `app.readPluginOptions()`/`savePluginOptions()` aren't actually symmetric despite what their doc
+ * comments imply: signalk-server's `readPluginOptions()` returns the *whole* on-disk file
+ * (`{ configuration, enabled, enableDebug, enableLogging }`), not just the `configuration` object
+ * `savePluginOptions()` writes into - see signalk-server's `interfaces/plugins.ts`
+ * (`appCopy.readPluginOptions = () => getPluginOptions(plugin.id)` vs.
+ * `appCopy.savePluginOptions = (configuration, cb) => savePluginOptions(id, { ...getPluginOptions(id), configuration }, cb)`).
+ * Spreading that return value straight back into a save call therefore nests the whole file one level
+ * deeper inside its own `configuration` key every time (see `support/signalk-einklabel-plugin.json` and
+ * `clearForceRepaint` in `./repaintScheduler.ts`). Unwrapping any such nesting and keeping only recognised
+ * fields here means every save collapses back down instead of growing, self-healing an already-corrupted file.
+ */
+function readCurrentConfig(app) {
+    let raw = app.readPluginOptions();
+    while (raw &&
+        typeof raw === "object" &&
+        "configuration" in raw &&
+        typeof raw.configuration === "object") {
+        raw = raw.configuration;
+    }
+    const result = {};
+    if (raw && typeof raw === "object") {
+        for (const key of PLUGIN_CONFIG_KEYS) {
+            if (key in raw) {
+                result[key] = raw[key];
+            }
+        }
+    }
+    return result;
+}
 /**
  * Resolves the user-facing `templatesDir` setting to an actual directory, mirroring
  * signalk-parquet's `outputDirectory` convention: empty means the default location, a relative
@@ -52,12 +102,13 @@ function resolveTemplatesDir(templatesDir) {
  * so the user can at least see what was found and report the PID; repainting such a device still
  * does nothing without a model override, since there's no width/height to render with) - plus, as a
  * fallback, whatever's already saved so an existing selection doesn't vanish from the dropdown just
- * because this particular run hasn't re-scanned it yet.
+ * because this particular run hasn't re-scanned it yet. `ALL_DEVICES` is always offered first,
+ * regardless of what's been scanned - see its own doc comment.
  */
 function deviceOptions(discovered, current) {
-    const values = [];
-    const labels = [];
-    const seen = new Set();
+    const values = [exports.ALL_DEVICES];
+    const labels = ["All discovered devices"];
+    const seen = new Set([exports.ALL_DEVICES]);
     for (const found of discovered) {
         if (found.pid === undefined) {
             continue;
@@ -97,14 +148,89 @@ function listSvgFiles(dir) {
         return [];
     }
 }
-/** Local templates take priority over a same-named bundled one; both show up as options. */
+const VARIANT_COLOUR_LETTERS = { B: "black", W: "white", R: "red", Y: "yellow" };
+const VARIANT_FILENAME = /^(\d+)x(\d+)-([BWRY]+)\.svg$/;
+/**
+ * Parses a template-family file name, e.g. `416x240-BWRY.svg` -> width 416, height 240, colours
+ * black/white/red/yellow (one letter per supported colour: B/W/R/Y). `undefined` for anything that
+ * doesn't match this convention, e.g. a plain, non-family template file.
+ */
+function parseTemplateVariant(fileName) {
+    const match = VARIANT_FILENAME.exec(fileName);
+    if (!match)
+        return undefined;
+    const colours = match[3].split("").map((letter) => VARIANT_COLOUR_LETTERS[letter]);
+    return { fileName, width: Number(match[1]), height: Number(match[2]), colours };
+}
+function listTemplateVariants(dir) {
+    return listSvgFiles(dir)
+        .map(parseTemplateVariant)
+        .filter((variant) => variant !== undefined);
+}
+/** A directory only counts as a template-family option if it actually has at least one parseable variant file in it - otherwise it's something else entirely, e.g. `.assets`. */
+function listTemplateFamilies(dir) {
+    let entries;
+    try {
+        entries = (0, fs_1.readdirSync)(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isDirectory() && listTemplateVariants((0, path_1.join)(dir, entry.name)).length > 0)
+        .map((entry) => entry.name);
+}
+/** Local templates (files or template-family directories) take priority over a same-named bundled one; both show up as options. */
 function templateNameOptions(templatesDir) {
-    const local = listSvgFiles(templatesDir);
-    const bundled = listSvgFiles(exports.BUNDLED_TEMPLATES_DIR).filter((name) => !local.includes(name));
+    const local = [...listSvgFiles(templatesDir), ...listTemplateFamilies(templatesDir)];
+    const bundled = [...listSvgFiles(exports.BUNDLED_TEMPLATES_DIR), ...listTemplateFamilies(exports.BUNDLED_TEMPLATES_DIR)].filter((name) => !local.includes(name));
     return [...local, ...bundled];
 }
-/** Resolves a template name to an actual file path - a local template overrides the bundled one of the same name. */
-function resolveTemplatePath(templatesDir, templateName) {
+function sameColours(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const setA = new Set(a);
+    return b.every((colour) => setA.has(colour));
+}
+/**
+ * Picks the best-fitting file within a template-family directory (see `parseTemplateVariant`) for a
+ * device's actual panel, trying each of these in turn: (1) an exact width/height/colour-set match,
+ * (2) width/height alone (ignoring colour-set) next, and (3) failing either, the nearest width -
+ * tie-broken by whichever candidate's own height/width ratio is closest to the target's, so a
+ * differently-proportioned panel doesn't just get an arbitrarily stretched/cropped near-width match.
+ */
+function pickBestVariant(variants, target) {
+    if (variants.length === 0)
+        return undefined;
+    const exact = variants.find((v) => v.width === target.width && v.height === target.height && sameColours(v.colours, target.colours));
+    if (exact)
+        return exact;
+    const sizeMatch = variants.find((v) => v.width === target.width && v.height === target.height);
+    if (sizeMatch)
+        return sizeMatch;
+    const targetRatio = target.height / target.width;
+    const nearestWidth = Math.min(...variants.map((v) => Math.abs(v.width - target.width)));
+    const nearestWidthCandidates = variants.filter((v) => Math.abs(v.width - target.width) === nearestWidth);
+    return nearestWidthCandidates.reduce((best, candidate) => Math.abs(candidate.height / candidate.width - targetRatio) < Math.abs(best.height / best.width - targetRatio) ? candidate : best);
+}
+/**
+ * Resolves a template name to an actual file path - a local template overrides the bundled one of the
+ * same name. `templateName` can also name a template-family *directory* (see `pickBestVariant`), in
+ * which case `target` (the device's actual width/height/colours) picks the best file inside it. A
+ * `target`-less call, or one where `templateName` just isn't a directory, falls through to the plain
+ * flat-file behaviour - the only kind the CLI (which always names an exact file) ever uses.
+ */
+function resolveTemplatePath(templatesDir, templateName, target) {
+    if (target) {
+        const dir = [(0, path_1.join)(templatesDir, templateName), (0, path_1.join)(exports.BUNDLED_TEMPLATES_DIR, templateName)].find((candidate) => (0, fs_1.existsSync)(candidate) && (0, fs_1.statSync)(candidate).isDirectory());
+        if (dir) {
+            const best = pickBestVariant(listTemplateVariants(dir), target);
+            if (!best) {
+                throw new Error(`template directory "${templateName}" has no valid "<width>x<height>-<colours>.svg" files`);
+            }
+            return (0, path_1.join)(dir, best.fileName);
+        }
+    }
     const localPath = (0, path_1.join)(templatesDir, templateName);
     return (0, fs_1.existsSync)(localPath) ? localPath : (0, path_1.join)(exports.BUNDLED_TEMPLATES_DIR, templateName);
 }
@@ -114,7 +240,7 @@ function withEnum(schema, values, names) {
 }
 function configSchema(app, discovered = []) {
     const defaults = defaultConfig();
-    const current = { ...defaults, ...app.readPluginOptions() };
+    const current = { ...defaults, ...readCurrentConfig(app) };
     const { values: deviceValues, labels: deviceLabels } = deviceOptions(discovered, current);
     return {
         type: "object",
@@ -130,7 +256,8 @@ function configSchema(app, discovered = []) {
             scanOnStart: {
                 type: "boolean",
                 title: "Scan for devices on plugin start",
-                description: 'Runs a short BLE scan so discovered devices show up in a device\'s "Device" picker below.',
+                description: 'Runs a short BLE scan so discovered devices show up in a device\'s "Device" picker below. ' +
+                    'Not needed if every device uses "All discovered devices" - that scans on demand instead.',
                 default: defaults.scanOnStart,
             },
             scanDurationSeconds: {
@@ -180,7 +307,9 @@ function configSchema(app, discovered = []) {
                         device: withEnum({
                             type: "string",
                             title: "Device",
-                            description: "Picked from devices found by a scan (plugin start, or `esl-cli scan`) - sets both the model and BLE address.",
+                            description: "Either a specific device found by a scan (plugin start, or `esl-cli scan`), setting both the model and BLE " +
+                                'address, or "All discovered devices" to paint this same template/trigger to every device the plugin currently ' +
+                                "knows about - simplest for a single label, and also covers several identical labels without listing each one.",
                         }, deviceValues, deviceLabels),
                         templateName: withEnum({ type: "string", title: "Template" }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
                         repaintTrigger: {

package/dist/devices/discoveredDevicesStore.d.ts

@@ -0,0 +1,32 @@
+import { ServerAPI } from "@signalk/server-api";
+import { DiscoveredDevice } from "./types";
+/**
+ * How long a previously-scanned device that isn't found again in a later scan is still kept as a
+ * dropdown option, before being dropped - covers a device that's simply asleep/out of BLE range for
+ * one scan, without keeping stale entries around forever. Not yet user-configurable.
+ */
+export declare const DISCOVERED_DEVICE_TTL_MS: number;
+export type DiscoveredDeviceRecord = DiscoveredDevice & {
+    lastSeenAt: number;
+};
+export type DiscoveredDevicesState = Record<string, DiscoveredDeviceRecord>;
+export declare function loadDiscoveredDevices(app: ServerAPI): DiscoveredDevicesState;
+/**
+ * Merges one scan's finds into the previously persisted set, keyed by BLE address (the one stable
+ * identifier across scans - see README's note on devices advertising under different names at
+ * different times). A device found again gets `lastSeenAt` bumped to `now`; one not found this time
+ * is kept as-is as long as it's within `DISCOVERED_DEVICE_TTL_MS` of its own `lastSeenAt`, and dropped
+ * once older than that - so the dropdown survives a plugin restart and the occasional missed scan,
+ * without accumulating devices that are gone for good.
+ */
+export declare function mergeDiscoveredDevices(previous: DiscoveredDevicesState, foundThisScan: DiscoveredDevice[], now: number): DiscoveredDevicesState;
+/** Loads the persisted set, merges in this scan's finds, saves the result, and returns it. */
+export declare function recordScanResults(app: ServerAPI, foundThisScan: DiscoveredDevice[], now?: number): DiscoveredDevicesState;
+/**
+ * Bumps a single device's `lastSeenAt` outside of a scan - called after a successful paint, since
+ * connecting to paint it is just as much positive proof it's still there as a discovery scan hit.
+ * Without this, a configured device that's actively being repainted (typically with `scanOnStart`
+ * off once set up, per the README) would otherwise silently age out of the persisted set after
+ * `DISCOVERED_DEVICE_TTL_MS` even though it's demonstrably still in range and working.
+ */
+export declare function touchDiscoveredDevice(app: ServerAPI, device: DiscoveredDevice, now?: number): void;

package/dist/devices/discoveredDevicesStore.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISCOVERED_DEVICE_TTL_MS = void 0;
+exports.loadDiscoveredDevices = loadDiscoveredDevices;
+exports.mergeDiscoveredDevices = mergeDiscoveredDevices;
+exports.recordScanResults = recordScanResults;
+exports.touchDiscoveredDevice = touchDiscoveredDevice;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * How long a previously-scanned device that isn't found again in a later scan is still kept as a
+ * dropdown option, before being dropped - covers a device that's simply asleep/out of BLE range for
+ * one scan, without keeping stale entries around forever. Not yet user-configurable.
+ */
+exports.DISCOVERED_DEVICE_TTL_MS = 24 * 60 * 60 * 1000;
+function storePath(app) {
+    return (0, path_1.join)(app.getDataDirPath(), "discovered-devices.json");
+}
+function loadDiscoveredDevices(app) {
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(storePath(app), "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function saveDiscoveredDevices(app, state) {
+    (0, fs_1.writeFileSync)(storePath(app), JSON.stringify(state));
+}
+/**
+ * Merges one scan's finds into the previously persisted set, keyed by BLE address (the one stable
+ * identifier across scans - see README's note on devices advertising under different names at
+ * different times). A device found again gets `lastSeenAt` bumped to `now`; one not found this time
+ * is kept as-is as long as it's within `DISCOVERED_DEVICE_TTL_MS` of its own `lastSeenAt`, and dropped
+ * once older than that - so the dropdown survives a plugin restart and the occasional missed scan,
+ * without accumulating devices that are gone for good.
+ */
+function mergeDiscoveredDevices(previous, foundThisScan, now) {
+    const next = {};
+    for (const found of foundThisScan) {
+        next[found.address] = { ...found, lastSeenAt: now };
+    }
+    for (const [address, record] of Object.entries(previous)) {
+        if (!(address in next) && now - record.lastSeenAt < exports.DISCOVERED_DEVICE_TTL_MS) {
+            next[address] = record;
+        }
+    }
+    return next;
+}
+/** Loads the persisted set, merges in this scan's finds, saves the result, and returns it. */
+function recordScanResults(app, foundThisScan, now = Date.now()) {
+    const merged = mergeDiscoveredDevices(loadDiscoveredDevices(app), foundThisScan, now);
+    saveDiscoveredDevices(app, merged);
+    return merged;
+}
+/**
+ * Bumps a single device's `lastSeenAt` outside of a scan - called after a successful paint, since
+ * connecting to paint it is just as much positive proof it's still there as a discovery scan hit.
+ * Without this, a configured device that's actively being repainted (typically with `scanOnStart`
+ * off once set up, per the README) would otherwise silently age out of the persisted set after
+ * `DISCOVERED_DEVICE_TTL_MS` even though it's demonstrably still in range and working.
+ */
+function touchDiscoveredDevice(app, device, now = Date.now()) {
+    const state = loadDiscoveredDevices(app);
+    state[device.address] = { ...device, lastSeenAt: now };
+    saveDiscoveredDevices(app, state);
+}

package/dist/devices/discoveryCoordinator.d.ts

@@ -0,0 +1,19 @@
+import { ServerAPI } from "@signalk/server-api";
+import { DiscoveredDevicesState } from "./discoveredDevicesStore";
+import { DiscoveredDevice } from "./types";
+export interface ScanResult {
+    /** Devices this particular scan actually found - distinct from `merged`, which also carries over anything still-fresh from before. */
+    foundThisScan: DiscoveredDevice[];
+    /** The full persisted set after merging `foundThisScan` in - see `discoveredDevicesStore.ts`. */
+    merged: DiscoveredDevicesState;
+}
+/** epoch ms a scan was started at, if one is currently running - `undefined` otherwise. */
+export declare function scanInProgressSince(): number | undefined;
+/**
+ * Runs one BLE discovery scan and persists what it finds. node-ble/BlueZ has no scan-cancellation
+ * API and can't run two discovery sessions at once, so a caller that arrives while a scan is
+ * already running (e.g. the startup scan and an on-demand scan for a `device: "ALL"` repaint both
+ * wanting to scan at the same moment) is hooked into that *same* in-flight scan's eventual result
+ * instead of starting a second BlueZ session, which would make both fail.
+ */
+export declare function ensureScan(app: ServerAPI, durationSeconds: number): Promise<ScanResult>;

package/dist/devices/discoveryCoordinator.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanInProgressSince = scanInProgressSince;
+exports.ensureScan = ensureScan;
+const bleDiscovery_1 = require("./bleDiscovery");
+const discoveredDevicesStore_1 = require("./discoveredDevicesStore");
+const registry_1 = require("./registry");
+let inFlight;
+/** epoch ms a scan was started at, if one is currently running - `undefined` otherwise. */
+function scanInProgressSince() {
+    return inFlight?.startedAt;
+}
+/**
+ * Runs one BLE discovery scan and persists what it finds. node-ble/BlueZ has no scan-cancellation
+ * API and can't run two discovery sessions at once, so a caller that arrives while a scan is
+ * already running (e.g. the startup scan and an on-demand scan for a `device: "ALL"` repaint both
+ * wanting to scan at the same moment) is hooked into that *same* in-flight scan's eventual result
+ * instead of starting a second BlueZ session, which would make both fail.
+ */
+function ensureScan(app, durationSeconds) {
+    if (inFlight) {
+        return inFlight.promise;
+    }
+    const promise = runScan(app, durationSeconds).finally(() => {
+        inFlight = undefined;
+    });
+    inFlight = { startedAt: Date.now(), promise };
+    return promise;
+}
+async function runScan(app, durationSeconds) {
+    const foundThisScan = [];
+    const drivers = (0, registry_1.allDrivers)();
+    try {
+        await (0, bleDiscovery_1.withDiscovery)(durationSeconds * 1000, async (adapter) => {
+            await (0, bleDiscovery_1.forEachAdvertisedDevice)(adapter, async ({ device, address, name, manufacturerId, manufacturerData }) => {
+                const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
+                if (!driver) {
+                    return;
+                }
+                const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData).catch((err) => {
+                    app.debug(`${driver.vendor} scan failed: ${err.message}\n${err.stack ?? ""}`);
+                    return undefined;
+                });
+                if (!found) {
+                    return;
+                }
+                foundThisScan.push(found);
+                const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, "0")}` : "unknown";
+                const hwid = found.hwVersion ?? "unknown";
+                app.debug(`discovered ${driver.vendor} device "${found.name ?? ""}" [${found.address}] pid=${pid} hwid=${hwid}`);
+            });
+        });
+    }
+    catch (err) {
+        app.debug(`scan failed: ${err.message}\n${err.stack ?? ""}`);
+    }
+    const merged = (0, discoveredDevicesStore_1.recordScanResults)(app, foundThisScan);
+    return { foundThisScan, merged };
+}