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

package/dist/devices/zhsunyco/encode.js

@@ -1,15 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.encodeBitmap = encodeBitmap;
-/** Mirrors the reference driver's `from_pillow` nearest-colour decision tree. */
-function nearestColour(r, g, b) {
+const WOLINK_CODE = {
+    black: 0 /* WolinkColour.Black */,
+    white: 1 /* WolinkColour.White */,
+    yellow: 2 /* WolinkColour.Yellow */,
+    red: 3 /* WolinkColour.Red */,
+};
+/**
+ * Where a classified colour isn't in a device's own palette, the nearest one that's actually
+ * supported - e.g. a BWR-only panel (no yellow layer) gets the yellow bucket's pixels sent as red,
+ * the closest available warm/accent colour, rather than a wire code the hardware doesn't render.
+ */
+const FALLBACK = {
+    yellow: "red",
+    red: "black",
+};
+/** Mirrors the reference driver's `from_pillow` nearest-colour decision tree, then maps the result down onto whatever colours this particular device's panel actually supports (see `DeviceMetadata.colours`). */
+function nearestColour(r, g, b, supported) {
+    let colour = "black";
     if (r > 150 && g > 150 && b > 150)
-        return 1 /* WolinkColour.White */;
-    if (r > 150 && g > 100 && b < 80)
-        return 2 /* WolinkColour.Yellow */;
-    if (r > 150 && g < 80 && b < 80)
-        return 3 /* WolinkColour.Red */;
-    return 0 /* WolinkColour.Black */;
+        colour = "white";
+    else if (r > 150 && g > 100 && b < 80)
+        colour = "yellow";
+    else if (r > 150 && g < 80 && b < 80)
+        colour = "red";
+    while (!supported.includes(colour)) {
+        const fallback = FALLBACK[colour];
+        if (!fallback)
+            break;
+        colour = fallback;
+    }
+    return WOLINK_CODE[colour];
 }
 /**
  * Quantises a common RGBA bitmap and packs it into the Wolink wire format: 2 bits per
@@ -32,7 +54,7 @@ function encodeBitmap(bitmap, metadata) {
         const physX = width - 1 - x;
         for (let y = 0; y < height; y++) {
             const srcY = y - voffset;
-            const colour = srcY >= 0 && srcY < bitmap.height ? samplePixel(bitmap, x, srcY) : 0 /* WolinkColour.Black */;
+            const colour = srcY >= 0 && srcY < bitmap.height ? samplePixel(bitmap, x, srcY, metadata.colours) : 0 /* WolinkColour.Black */;
             const physY = height - 1 - y;
             const byteIdx = physX * bytesPerColumn + Math.floor(physY / 4);
             const bitShift = 6 - (physY % 4) * 2;
@@ -41,7 +63,7 @@ function encodeBitmap(bitmap, metadata) {
     }
     return data;
 }
-function samplePixel(bitmap, x, y) {
+function samplePixel(bitmap, x, y, supported) {
     const offset = (y * bitmap.width + x) * 4;
-    return nearestColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2]);
+    return nearestColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2], supported);
 }

package/dist/devices/zhsunyco/index.js

@@ -150,7 +150,7 @@ async function readDeviceDetails(device, address, advertisedInfo) {
     // which otherwise stays set forever and silently skips every later scan).
     return Promise.race([
         read(),
-        (0, bleDiscovery_1.sleep)(SCAN_CONNECT_TIMEOUT_MS * 2).then(() => {
+        (0, bleDiscovery_1.sleep)(SCAN_CONNECT_TIMEOUT_MS * 3).then(() => {
             console.error(`${pluginVersion_1.PLUGIN_NAME}: zhsunyco [${address}]: battery/config read timed out after ${SCAN_CONNECT_TIMEOUT_MS * 2}ms`);
             return fallback;
         }),

package/dist/plugin.js

@@ -4,69 +4,44 @@ exports.createPlugin = createPlugin;
 const config_1 = require("./config");
 const registry_1 = require("./devices/registry");
 const zhsunyco_1 = require("./devices/zhsunyco");
-const bleDiscovery_1 = require("./devices/bleDiscovery");
+const discoveryCoordinator_1 = require("./devices/discoveryCoordinator");
+const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const repaintScheduler_1 = require("./repaintScheduler");
 /** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
-async function runStartupScan(app, discovered, durationSeconds) {
-    app.setPluginStatus(`Scanning for ESL devices for ${durationSeconds}s...`);
-    const startedAt = Date.now();
-    let scanError;
-    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) => {
-                    scanError = `${driver.vendor} scan failed: ${err.message}`;
-                    app.debug(`${scanError}\n${err.stack ?? ""}`);
-                    return undefined;
-                });
-                if (!found) {
-                    return;
-                }
-                discovered.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}`);
-            });
-        });
+async function runStartupScan(app, durationSeconds) {
+    const alreadyRunning = (0, discoveryCoordinator_1.scanInProgressSince)();
+    if (alreadyRunning !== undefined) {
+        const elapsedSeconds = ((Date.now() - alreadyRunning) / 1000).toFixed(0);
+        app.debug(`a scan from before this restart is still running (${elapsedSeconds}s) - joining it instead of starting a second BLE session`);
+        app.setPluginStatus(`Waiting for a scan already running from before this restart (${elapsedSeconds}s so far) to finish updating the "Device" picker below...`);
     }
-    catch (err) {
-        // Without this, an error thrown anywhere in the discovery window (e.g. BlueZ dropping the
-        // D-Bus connection) skips every line below, leaving the admin UI stuck on "Scanning..."
-        // forever even though `discovered` may already hold devices found before the failure.
-        scanError = `scan failed: ${err.message}`;
-        app.debug(`${scanError}\n${err.stack ?? ""}`);
+    else {
+        app.setPluginStatus(`Scanning for ESL devices for ${durationSeconds}s...`);
     }
-    // Surfaces the real cause in the admin UI (instead of only the debug log) - a scan that
-    // ends in well under its configured duration is almost always this, not "no devices nearby".
-    app.setPluginError(scanError ?? "");
+    const startedAt = Date.now();
+    const { foundThisScan } = await (0, discoveryCoordinator_1.ensureScan)(app, durationSeconds).catch((err) => {
+        app.debug(`startup scan failed: ${err.message}`);
+        return { foundThisScan: [] };
+    });
     const elapsedSeconds = ((Date.now() - startedAt) / 1000).toFixed(1);
-    if (discovered.length === 0) {
+    if (foundThisScan.length === 0) {
         app.setPluginStatus(`Scan complete - no ESL devices found nearby after ${elapsedSeconds} seconds.`);
         return;
     }
-    const summary = discovered.map((device) => `${device.name ?? device.vendor} [${device.address}]`).join(", ");
-    app.setPluginStatus(`Scan complete - found ${discovered.length} device(s) in ${elapsedSeconds}s: ${summary} - pick one from a device's "Device" field below`);
+    const summary = foundThisScan.map((device) => `${device.name ?? device.vendor} [${device.address}]`).join(", ");
+    app.setPluginStatus(`Scan complete - found ${foundThisScan.length} device(s) in ${elapsedSeconds}s: ${summary} - pick one from a device's "Device" field below`);
 }
 function createPlugin(app) {
     (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
     let scheduler;
-    const lastDiscovered = [];
-    // node-ble/BlueZ has no scan-cancellation API, so a scan started by a previous start()
-    // keeps running its full duration even after stop() - tracking it here stops a quick
-    // disable/re-enable from opening a second concurrent D-Bus/BlueZ session, which was
-    // making the new scan fail (and report "no devices found") almost immediately.
-    let scanInProgress;
-    let scanStartedAt;
     const plugin = {
         id: "signalk-einklabel-plugin",
         name: "eInk ESL (Electronic Shelf Label)",
         description: "Renders selected SignalK data to BLE eInk Electronic Shelf Labels",
-        schema: () => (0, config_1.configSchema)(app, lastDiscovered),
+        // Read fresh from disk on every call (rather than cached in memory) so it reflects whichever scan
+        // last completed - the startup scan below, an on-demand scan for a `device: "ALL"` repaint (see
+        // `resolveTargets` in `repaintScheduler.ts`), or `esl-cli scan` - regardless of which one wrote it.
+        schema: () => (0, config_1.configSchema)(app, Object.values((0, discoveredDevicesStore_1.loadDiscoveredDevices)(app))),
         uiSchema: () => (0, config_1.configUiSchema)(),
         start(config) {
             const pluginConfig = {
@@ -75,21 +50,7 @@ function createPlugin(app) {
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
             if (pluginConfig.scanOnStart) {
-                if (scanInProgress) {
-                    const elapsedSeconds = ((Date.now() - (scanStartedAt ?? Date.now())) / 1000).toFixed(0);
-                    app.debug(`a scan from before this restart is still running (${elapsedSeconds}s) - skipping a new one to avoid a second concurrent BLE session`);
-                    app.setPluginStatus(`Skipped startup scan - a scan from before this restart is still finishing (running ${elapsedSeconds}s) and will update the "Device" picker below once it does.`);
-                }
-                else {
-                    lastDiscovered.length = 0;
-                    scanStartedAt = Date.now();
-                    const scan = runStartupScan(app, lastDiscovered, pluginConfig.scanDurationSeconds).catch((err) => app.debug(`startup scan failed: ${err.message}`));
-                    scanInProgress = scan;
-                    void scan.finally(() => {
-                        scanInProgress = undefined;
-                        scanStartedAt = undefined;
-                    });
-                }
+                void runStartupScan(app, pluginConfig.scanDurationSeconds);
             }
             scheduler = (0, repaintScheduler_1.startRepaintScheduler)(app, pluginConfig);
         },

package/dist/render/assets.d.ts

@@ -7,7 +7,7 @@
 export declare function normalizeAssetKey(value: unknown): string | undefined;
 /**
  * Resolves an `assets=` binding to an actual `.svg` file, looked up as `<key>.svg` inside whichever
- * `assets/<assetsName>` directory `selectAssetsDir` picks. `undefined` if that directory has no
+ * `.assets/<assetsName>` directory `selectAssetsDir` picks. `undefined` if that directory has no
  * matching file, which callers treat as "no image" rather than an error, since an unmapped value
  * (e.g. a phase name the asset set doesn't cover) is an expected, not exceptional, case.
  */
@@ -21,3 +21,9 @@ export declare function resolveAssetPath(templatesDir: string, bundledTemplatesD
  * directory, is readable) - the miss is then just this value's.
  */
 export declare function describeAssetsDirProblem(templatesDir: string, bundledTemplatesDir: string, assetsName: string): string | undefined;
+/**
+ * Counts the `.svg` files in whichever `.assets/<assetsName>` directory `selectAssetsDir` would read
+ * from, for a caller to report alongside a resolved-but-empty-key miss - confirms which directory is in
+ * play and how populated it is, which "the directory exists" alone doesn't convey.
+ */
+export declare function countAssets(templatesDir: string, bundledTemplatesDir: string, assetsName: string): number;

package/dist/render/assets.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeAssetKey = normalizeAssetKey;
 exports.resolveAssetPath = resolveAssetPath;
 exports.describeAssetsDirProblem = describeAssetsDirProblem;
+exports.countAssets = countAssets;
 const fs_1 = require("fs");
 const path_1 = require("path");
 /**
@@ -22,18 +23,20 @@ function normalizeAssetKey(value) {
     return normalized || undefined;
 }
 /**
- * Picks which `assets/<assetsName>` directory an `assets=` binding should read from - the user's own
- * `templatesDir/assets/<assetsName>` if it exists as a directory at all, otherwise
- * `bundledTemplatesDir/assets/<assetsName>` (see `BUNDLED_TEMPLATES_DIR` in `../config.ts`). This is a
- * whole-directory choice, not a per-file merge: a user who provides their own `assets/lunar_phases`
- * directory (even a partial one, missing some phases) gets exactly that directory and nothing from the
- * bundled set, so it's always clear which files are in play - see the module's "overrides only work at
- * directory level" design note. This choice is independent of which template file (bundled or a user
- * override) ended up being rendered, so a user can override just a template, just its resources, or
- * both, in any combination.
+ * Picks which `.assets/<assetsName>` directory an `assets=` binding should read from - the user's own
+ * `templatesDir/.assets/<assetsName>` if it exists as a directory at all, otherwise
+ * `bundledTemplatesDir/.assets/<assetsName>` (see `BUNDLED_TEMPLATES_DIR` in `../config.ts`). Dot-prefixed
+ * so it reads as internal machinery rather than a selectable item - it lives alongside template-family
+ * directories like `tides/` (see `pickBestVariant` in `../config.ts`), which are offered in the "Template"
+ * dropdown, and `.assets` plainly isn't one of those. This is a whole-directory choice, not a per-file
+ * merge: a user who provides their own `.assets/lunar_phases` directory (even a partial one, missing some
+ * phases) gets exactly that directory and nothing from the bundled set, so it's always clear which files
+ * are in play - see the module's "overrides only work at directory level" design note. This choice is
+ * independent of which template file (bundled or a user override) ended up being rendered, so a user can
+ * override just a template, just its resources, or both, in any combination.
  */
 function selectAssetsDir(templatesDir, bundledTemplatesDir, assetsName) {
-    const userDir = (0, path_1.join)(templatesDir, "assets", assetsName);
+    const userDir = (0, path_1.join)(templatesDir, ".assets", assetsName);
     try {
         if ((0, fs_1.statSync)(userDir).isDirectory())
             return userDir;
@@ -41,11 +44,11 @@ function selectAssetsDir(templatesDir, bundledTemplatesDir, assetsName) {
     catch {
         // doesn't exist (or isn't readable) - fall through to the bundled directory
     }
-    return (0, path_1.join)(bundledTemplatesDir, "assets", assetsName);
+    return (0, path_1.join)(bundledTemplatesDir, ".assets", assetsName);
 }
 /**
  * Resolves an `assets=` binding to an actual `.svg` file, looked up as `<key>.svg` inside whichever
- * `assets/<assetsName>` directory `selectAssetsDir` picks. `undefined` if that directory has no
+ * `.assets/<assetsName>` directory `selectAssetsDir` picks. `undefined` if that directory has no
  * matching file, which callers treat as "no image" rather than an error, since an unmapped value
  * (e.g. a phase name the asset set doesn't cover) is an expected, not exceptional, case.
  */
@@ -86,3 +89,16 @@ function describeAssetsDirProblem(templatesDir, bundledTemplatesDir, assetsName)
     const problem = describeDir(selectAssetsDir(templatesDir, bundledTemplatesDir, assetsName));
     return problem && `assets directory ${problem}`;
 }
+/**
+ * Counts the `.svg` files in whichever `.assets/<assetsName>` directory `selectAssetsDir` would read
+ * from, for a caller to report alongside a resolved-but-empty-key miss - confirms which directory is in
+ * play and how populated it is, which "the directory exists" alone doesn't convey.
+ */
+function countAssets(templatesDir, bundledTemplatesDir, assetsName) {
+    try {
+        return (0, fs_1.readdirSync)(selectAssetsDir(templatesDir, bundledTemplatesDir, assetsName)).filter((name) => name.endsWith(".svg")).length;
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/render/svgRenderer.js

@@ -136,7 +136,7 @@ class SvgRenderer {
                     console.error(key
                         ? `${pluginVersion_1.PLUGIN_NAME}: image "${descElement.textContent}" has no asset file for value "${key}" in "${binding.assets}"`
                         : `${pluginVersion_1.PLUGIN_NAME}: image "${descElement.textContent}" resolved to empty value to select asset`);
-                    console.error(`${pluginVersion_1.PLUGIN_NAME}: ${dirProblem ?? `assets directory for "${binding.assets}" is present`}`);
+                    console.error(`${pluginVersion_1.PLUGIN_NAME}: ${dirProblem ?? `directory "${binding.assets}" found with ${(0, assets_1.countAssets)(templatesDir, bundledTemplatesDir, binding.assets)} assets`}`);
                     element.parentNode?.removeChild(element);
                     continue;
                 }

package/dist/repaintScheduler.js

@@ -7,6 +7,8 @@ const path_1 = require("path");
 const fs_1 = require("fs");
 const config_1 = require("./config");
 const bleDiscovery_1 = require("./devices/bleDiscovery");
+const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
+const discoveryCoordinator_1 = require("./devices/discoveryCoordinator");
 const registry_1 = require("./devices/registry");
 const svgRenderer_1 = require("./render/svgRenderer");
 const binding_1 = require("./render/binding");
@@ -16,8 +18,10 @@ const unitCategories_1 = require("./unitCategories");
 const pathMeta_1 = require("./pathMeta");
 const resolveApiUrl_1 = require("./resolveApiUrl");
 const pluginVersion_1 = require("./pluginVersion");
+const httpJson_1 = require("./httpJson");
 const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
+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
  * periodic check (below, in `startRepaintScheduler`) would fire at - every `intervalHours` hours,
@@ -60,9 +64,13 @@ function stableStringify(value) {
     }
     return JSON.stringify(value);
 }
-/** Hashes both the live data context and the template's mtime, so editing a template (even with no data change) triggers a repaint. */
-function hashContext(context, templateMtimeMs) {
-    return (0, crypto_1.createHash)("sha1").update(stableStringify(context)).update(String(templateMtimeMs)).digest("hex");
+/** Hashes the template's mtime, so editing a template (even with no data change) triggers a repaint. */
+function hashTemplate(templateMtimeMs) {
+    return (0, crypto_1.createHash)("sha1").update(String(templateMtimeMs)).digest("hex");
+}
+/** Hashes the live data context, so a data change triggers a repaint even with the template untouched. */
+function hashData(context) {
+    return (0, crypto_1.createHash)("sha1").update(stableStringify(context)).digest("hex");
 }
 /** Merges `value` into `target` at the nested location described by a dotted SignalK path. */
 function setAtPath(target, path, value) {
@@ -85,13 +93,16 @@ function setAtPath(target, path, value) {
  * CLI's HTTP-fetched equivalent (`assembleLiveContext` in `cli/liveContext.ts`), so a `path=` binding
  * resolves to the same value either way - without it, `resolveBinding` would hand back the whole
  * wrapper object instead of e.g. a plain string, breaking any binding that expects one (a `<image>`'s
- * `assets=`, a `format=` formatter, etc). `resources`-sourced bindings go through `app.resourcesApi`,
- * in-process too, with no such wrapper. Per-path unit-conversion metadata (`pathMeta`, for automatic
- * conversion - see `renderBinding`) and an explicit `category=` binding's resolved conversion both
- * have no in-process equivalent (confirmed against the signalk-server source - that resolution only
- * happens in its REST layer), so both need `apiUrl` - fetching `pathMeta` is best-effort (a
- * missing/unreachable server just means no automatic conversion), but a `category=` binding is a
- * declared dependency, so a missing `apiUrl` is a hard error there.
+ * `assets=`, a `format=` formatter, etc). `resources`-sourced bindings with no `provider=` pin go
+ * through `app.resourcesApi` in-process too, with no such wrapper - but a `provider=`-pinned binding
+ * goes over HTTP instead (see the resources loop below), since the in-process API doesn't actually
+ * honor `providerId` on signalk-server 2.30.0. Per-path unit-conversion metadata (`pathMeta`, for
+ * automatic conversion - see `renderBinding`) and an explicit `category=` binding's resolved
+ * conversion both have no in-process equivalent (confirmed against the signalk-server source - that
+ * resolution only happens in its REST layer), so both need `apiUrl` - fetching `pathMeta` is
+ * best-effort (a missing/unreachable server just means no automatic conversion), but a `category=`
+ * binding (and now a `provider=`-pinned resource binding) is a declared dependency, so a missing
+ * `apiUrl` is a hard error there.
  */
 async function assembleRawContext(app, apiUrl, bindings) {
     var _a;
@@ -130,13 +141,26 @@ async function assembleRawContext(app, apiUrl, bindings) {
         resourceBindings.set((0, binding_1.resourceContextKey)(binding), binding);
     }
     for (const [key, binding] of resourceBindings) {
-        // `listResources`'s type only allows the standard SignalKResourceType union, but the underlying
-        // Resources API (and a custom provider like signalk-tides, registered under the non-standard
-        // "tides" type) accepts any registered resource type string - this cast matches `getResource`'s
-        // wider, accurate signature. An explicit `provider=` pins which registered provider plugin
-        // answers the request (SignalK's `listResources(resType, params, providerId)`) rather than
-        // leaving it to whichever provider the server considers the default for that resource type.
-        resources[key] = await app.resourcesApi.listResources(binding.resource, {}, binding.provider);
+        if (binding.provider) {
+            // `app.resourcesApi.listResources(resType, params, providerId)` validates providerId against the
+            // registered providers but then - confirmed against signalk-server 2.30.0's own source - ignores
+            // it and merges every registered provider's results together (its internal `listFromAll`), so a
+            // second provider for the same resource type can silently clobber the one a binding pinned. The
+            // REST API's own `?provider=` query param doesn't have this bug (it queries only that provider),
+            // so a pinned binding goes over HTTP instead of the in-process API to actually get what it asked for.
+            if (!apiUrl) {
+                throw new Error(`binding pins resource "${binding.resource}" to provider "${binding.provider}" but no SignalK API base URL is configured`);
+            }
+            resources[key] = await (0, httpJson_1.fetchJson)(`${apiUrl}${RESOURCES_API_PATH}/${binding.resource}?provider=${encodeURIComponent(binding.provider)}`);
+        }
+        else {
+            // `listResources`'s type only allows the standard SignalKResourceType union, but the underlying
+            // Resources API (and a custom provider like signalk-tides, registered under the non-standard
+            // "tides" type) accepts any registered resource type string - this cast matches `getResource`'s
+            // wider, accurate signature. No `provider=` pin here, so the in-process call's default-provider
+            // behavior (whichever the server picks) is fine - and cheaper than a redundant HTTP round trip.
+            resources[key] = await app.resourcesApi.listResources(binding.resource, {}, undefined);
+        }
     }
     const categoryNames = new Set(bindings.filter((binding) => binding.category).map((binding) => binding.category));
     if (categoryNames.size > 0 && !apiUrl) {
@@ -146,33 +170,77 @@ async function assembleRawContext(app, apiUrl, bindings) {
     return { signalk, resources, pathMeta, categories };
 }
 function clearForceRepaint(app, friendlyName) {
-    const current = { ...app.readPluginOptions() };
+    const current = (0, config_1.readCurrentConfig)(app);
     const devices = (current.devices ?? []).map((device) => device.friendlyName === friendlyName ? { ...device, forceRepaint: false } : device);
     app.savePluginOptions({ ...current, devices }, (err) => {
         if (err)
             app.debug(`failed to clear forceRepaint for "${friendlyName}": ${err.message}`);
     });
 }
-async function considerRepaint(app, config, device, state, getApiUrl) {
+/** `RepaintState` key for one physical device under a given `DeviceConfig` entry - see `RepaintState`'s doc comment on why address is part of the key. */
+function stateKeyFor(friendlyName, address) {
+    return `${friendlyName}:${address}`;
+}
+function resolveTarget(vendor, pid, hwVersion, address) {
+    const driver = (0, registry_1.getDriver)(vendor);
+    const metadata = pid !== undefined ? driver?.metadataForPid(pid, hwVersion) : undefined;
+    return driver && pid !== undefined && metadata ? { address, vendor, pid, hwVersion, metadata, driver } : undefined;
+}
+/**
+ * Resolves a `DeviceConfig` entry to the physical device(s) it should paint. A specific
+ * `"<vendor>:<pid>[:<hwVersion>]@<address>"` resolves to exactly that one device (or none, if its
+ * driver/model can't be found). `ALL_DEVICES` resolves to every currently-known discovered device
+ * (see `discoveredDevicesStore.ts`) - if none are known yet, it triggers an on-demand scan first
+ * (bounded by `config.scanDurationSeconds`, same as the startup scan), so a first-time "ALL" setup
+ * doesn't require `scanOnStart` or a manual `esl-cli scan`.
+ */
+async function resolveTargets(app, config, device) {
+    if (device.device === config_1.ALL_DEVICES) {
+        let records = (0, discoveredDevicesStore_1.loadDiscoveredDevices)(app);
+        if (Object.keys(records).length === 0) {
+            app.debug(`"${device.friendlyName}": device is "${config_1.ALL_DEVICES}" and nothing discovered yet - scanning for ${config.scanDurationSeconds}s`);
+            records = (await (0, discoveryCoordinator_1.ensureScan)(app, config.scanDurationSeconds)).merged;
+        }
+        const targets = [];
+        for (const record of Object.values(records)) {
+            const target = resolveTarget(record.vendor, record.pid, record.hwVersion, record.address);
+            if (target)
+                targets.push(target);
+        }
+        return targets;
+    }
     const model = (0, config_1.parseDevice)(device.device);
-    const driver = model && (0, registry_1.getDriver)(model.vendor);
-    const metadata = model && driver?.metadataForPid(model.pid, model.hwVersion);
-    if (!model || !driver || !metadata) {
+    const target = model && resolveTarget(model.vendor, model.pid, model.hwVersion, model.address);
+    if (!target) {
         app.debug(`"${device.friendlyName}": no driver/metadata for device "${device.device}", skipping`);
-        return;
+        return [];
     }
+    return [target];
+}
+async function considerRepaint(app, config, device, target, state, getApiUrl) {
+    const { address, metadata, driver } = target;
+    const label = `"${device.friendlyName}" [${address}]`;
     const templatesDir = (0, config_1.resolveTemplatesDir)(config.templatesDir);
-    const templatePath = (0, config_1.resolveTemplatePath)(templatesDir, device.templateName);
+    const templatePath = (0, config_1.resolveTemplatePath)(templatesDir, device.templateName, {
+        width: metadata.width,
+        height: metadata.height,
+        colours: metadata.colours,
+    });
     const templateMtimeMs = (0, fs_1.statSync)(templatePath).mtimeMs;
     const bindings = (0, binding_1.findBindings)((0, fs_1.readFileSync)(templatePath, "utf-8"));
     const apiUrl = await getApiUrl().catch((err) => {
-        app.debug(`"${device.friendlyName}": ${err.message}`);
+        app.debug(`${label}: ${err.message}`);
         return undefined;
     });
     const rawContext = await assembleRawContext(app, apiUrl, bindings);
-    const hash = hashContext(rawContext, templateMtimeMs);
-    if (state[device.friendlyName]?.hash === hash && !device.forceRepaint) {
-        app.debug(`"${device.friendlyName}": data unchanged, skipping repaint`);
+    const templateHash = hashTemplate(templateMtimeMs);
+    const dataHash = hashData(rawContext);
+    const stateKey = stateKeyFor(device.friendlyName, address);
+    const previous = state[stateKey];
+    const templateChanged = previous?.templateHash !== templateHash;
+    const dataChanged = previous?.dataHash !== dataHash;
+    if (!templateChanged && !dataChanged && !device.forceRepaint) {
+        app.debug(`${label}: data unchanged, skipping repaint`);
         return;
     }
     const renderContext = {
@@ -189,18 +257,23 @@ async function considerRepaint(app, config, device, state, getApiUrl) {
     let paintDurationMs = 0;
     await (0, bleDiscovery_1.withRetries)(config.paintRetries, async (attempt) => {
         if (attempt > 1) {
-            app.debug(`"${device.friendlyName}": attempting paint ${attempt}/${config.paintRetries}`);
+            app.debug(`${label}: attempting paint ${attempt}/${config.paintRetries}`);
         }
         const startedAt = Date.now();
-        await driver.paint(bitmap, { address: model.address, aesKey: device.aesKey, connectTimeoutMs });
+        await driver.paint(bitmap, { address, aesKey: device.aesKey, connectTimeoutMs });
         paintDurationMs = Date.now() - startedAt;
     });
-    state[device.friendlyName] = { hash, repaintedAt: Date.now() };
+    (0, discoveredDevicesStore_1.touchDiscoveredDevice)(app, { address, vendor: target.vendor, pid: target.pid, hwVersion: target.hwVersion, metadata });
+    state[stateKey] = { templateHash, dataHash, repaintedAt: Date.now() };
     saveState(app, state);
-    if (device.forceRepaint) {
-        clearForceRepaint(app, device.friendlyName);
-    }
-    app.debug(`"${device.friendlyName}": repainted (paint took ${paintDurationMs}ms)`);
+    const reason = device.forceRepaint
+        ? "forced"
+        : templateChanged && dataChanged
+            ? "template and data changed"
+            : templateChanged
+                ? "template changed"
+                : "data changed";
+    app.debug(`${label}: repainted (${reason}, paint took ${paintDurationMs}ms)`);
 }
 function startRepaintScheduler(app, config) {
     const state = loadState(app);
@@ -213,13 +286,28 @@ function startRepaintScheduler(app, config) {
     // (startup check, interval, subscription alike) funnels through this one gate.
     const startedAt = Date.now();
     const settleMs = (config.settleSeconds ?? 120) * 1000;
-    const repaint = (device) => {
+    const repaint = async (device) => {
         const elapsedMs = Date.now() - startedAt;
         if (elapsedMs < settleMs) {
             app.debug(`"${device.friendlyName}": still settling (${Math.round(elapsedMs / 1000)}s/${Math.round(settleMs / 1000)}s) - skipping repaint`);
-            return Promise.resolve();
+            return;
+        }
+        const targets = await resolveTargets(app, config, device);
+        if (targets.length === 0) {
+            return;
+        }
+        const results = await Promise.allSettled(targets.map((target) => considerRepaint(app, config, device, target, state, getApiUrl)));
+        results.forEach((result, i) => {
+            if (result.status === "rejected") {
+                app.debug(`"${device.friendlyName}" [${targets[i].address}]: repaint failed: ${result.reason.message}`);
+            }
+        });
+        // A single `forceRepaint` flag covers every target under `ALL_DEVICES` too - only clear it once
+        // every target has actually succeeded, so a target that failed still gets forced again next time
+        // instead of quietly reverting to ordinary hash-based dedup.
+        if (device.forceRepaint && results.every((result) => result.status === "fulfilled")) {
+            clearForceRepaint(app, device.friendlyName);
         }
-        return considerRepaint(app, config, device, state, getApiUrl).catch((err) => app.debug(`"${device.friendlyName}": repaint failed: ${err.message}`));
     };
     const intervalDevices = config.devices.filter((device) => device.repaintTrigger === "interval");
     if (intervalDevices.length > 0) {
@@ -259,13 +347,17 @@ function startRepaintScheduler(app, config) {
     // it's actually overdue - already painted for the current scheduled slot (e.g. plugin restarted
     // mid-way through its interval) just waits for the regular periodic check above to hit the *next*
     // slot, rather than jumping the gun with an extra unscheduled paint every time the plugin restarts.
+    // `ALL_DEVICES` can't be cheaply pre-checked this way without resolving targets first (which may
+    // itself trigger a scan) - it always falls through to `repaint()`, whose own per-target hash dedup
+    // still avoids a redundant paint once targets are resolved.
     const startupCheckTimer = setTimeout(() => {
         for (const device of config.devices) {
-            if (device.repaintTrigger === "interval" && !device.forceRepaint) {
+            if (device.repaintTrigger === "interval" && !device.forceRepaint && device.device !== config_1.ALL_DEVICES) {
                 const hours = device.intervalHours ?? 1;
                 const minute = device.intervalMinute ?? 0;
                 const dueSlot = mostRecentScheduledSlot(new Date(), hours, minute);
-                const repaintedAt = state[device.friendlyName]?.repaintedAt;
+                const address = (0, config_1.parseDevice)(device.device)?.address;
+                const repaintedAt = address !== undefined ? state[stateKeyFor(device.friendlyName, address)]?.repaintedAt : undefined;
                 if (repaintedAt !== undefined && repaintedAt >= dueSlot.getTime()) {
                     app.debug(`"${device.friendlyName}": already painted for the current ${hours}h schedule slot - skipping startup catch-up`);
                     continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "0.8.1",
+  "version": "0.9.0-beta1",
   "description": "Display SignalK data on eInk Electronic Shelf Labels",
   "keywords": [
     "ble",

package/templates/{assets → .assets}/lunar_phases/README.md

@@ -10,9 +10,13 @@ Embed any of these in a template as a placeholder and set the `description`
 property to `path=environment.moon.phaseName,assets=lunar_phases`
 
 The image will be replaced at rendering time by the one matching the phase name.
-This will automatically adapt from `Waxing Gibbous` to `waxing_gibbous.svg`
+This will automatically adapt from 'Waxing Gibbous' to `waxing_gibbous.svg`
 
 ## Replacing
 
-Define your own template directory in the plugin configuration, and add an `assets/lunar_phases` directory path beneath it. You will need a complete set of phases in
+Define your own template directory in the plugin configuration, and add an `.assets/lunar_phases` directory path beneath it. You will need a complete set of phases in
 the new directory, its not possible to override only one of them.
+
+## Quirks
+
+'Third Quarter' is also known as 'Last Quarter' so the image is present under both names.