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

package/CHANGELOG.md

@@ -1,14 +1,20 @@
 # 0.9.0
 
+## Tide Clock Example
 - 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
+- Added a simpler *250x128* version of tide clock for 2.13" labels
+## Fixes
 - 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
+and data changes
 - Fix most cases of scanned devices not appearing in device dropdown choice
+## Improvements
+- Repaint state used to track which labels to repaint separately tracks the template 
 - `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
+## Device Selection
+- New 'ALL' as device option, and by default disable initial scan, to optimize support for single devices, so can configure and go without waiting for scan
+  - Scan and explicit device selection only required for boats with multiple ESL devices
+## Templating
 - 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`

package/README.md

@@ -72,12 +72,17 @@ npm install @rhizomatics/signalk-einklabel-plugin
 
 ![Tide Clock](docs/assets/screenshots/example_tidal_clock.png)
 
-The tide clock needs the [signalk-tides](https://github.com/openwatersio/signalk-tides) plugin to be installed and publishing tides to the Resources API. The [tide.svg](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tide.svg) can be customized to run with other APIs or take data only from SignalK data paths. For example, `source=resources,resource=tides,provider=tides,path=extremes[0].time,format=local_time` gets the first tide time, ensures its the preferred `signalk-tides` provider and makes it a simple local time rather than a UTC date time.
+Template available as 416x240-BWRY for 3.7" ESLs and a simpler template, sized 250x128, also BWRY, for the cheapest 2.13" labels.
 
-To show the lunar phase, the `environment.moon.phaseName` path is required, which can
+#### Pre-requisites
+
+* [signalk-tides](https://github.com/openwatersio/signalk-tides) plugin to be installed and publishing tides to the Resources API. 
+  - The [tides](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tides/) templates can be customized to run with other APIs or take data only from SignalK data paths. 
+  - In the template it uses paths like `source=resources,resource=tides,provider=tides,path=extremes[0].time,format=local_time` to get the first tide time, ensures its the preferred `signalk-tides` provider and makes it a simple local time rather than a UTC date time.
+* To show the lunar phase, the `environment.moon.phaseName` path is required, which can
 be easily achieved by installing and configuring the `derived-data` plugin.
 
-## Configuration
+## Configuration
 
 Use the standard configuration option in the SignalK menu for the plugin.
 
@@ -95,7 +100,7 @@ The plugin can optionally re-scan whenever it starts up (off by default), althou
 
 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
+### Scheduling
 
 There are two ways of scheduling scans:
 
@@ -323,6 +328,8 @@ For example, `npx esl-cli fields -t templates/tide.svg -e examples` will show al
 
 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.
 
+Easiest way to solve this is to choose 'All Discovered Devices' in the device configuration, and it will paint any compatible devices it finds on future scans.
+
 ### 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.

package/dist/config.d.ts

@@ -94,19 +94,18 @@ export interface PluginConfig {
  */
 export declare const BUNDLED_TEMPLATES_DIR: string;
 export declare function defaultConfig(): PluginConfig;
+export declare function readCurrentConfig(app: ServerAPI): Partial<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.
+ * Actively rewrites the on-disk file once it's nested (see `readCurrentConfig`'s doc comment) -
+ * `readCurrentConfig` alone only self-heals in memory for callers that go through it, but the admin
+ * UI's own config-editing form round-trips whatever raw JSON it was handed verbatim, including a
+ * stray nested `configuration` key it never touches (no schema field maps to it) - so left alone,
+ * every future save from the UI keeps re-persisting that dead weight forever (see
+ * `support/signalk-einklabel-plugin.json`). Called once at plugin start, which - unlike
+ * `clearForceRepaint` - isn't gated on any device having `forceRepaint` set, so a nested file gets
+ * flattened even if nothing ever triggers that path.
  */
-export declare function readCurrentConfig(app: ServerAPI): Partial<PluginConfig>;
+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

package/dist/config.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
 exports.defaultConfig = defaultConfig;
 exports.readCurrentConfig = readCurrentConfig;
+exports.healNestedConfig = healNestedConfig;
 exports.resolveTemplatesDir = resolveTemplatesDir;
 exports.parseDevice = parseDevice;
 exports.resolveTemplatePath = resolveTemplatePath;
@@ -65,14 +66,21 @@ const PLUGIN_CONFIG_KEYS = [
  * `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();
+function unwrapNestedConfiguration(raw) {
+    let levels = 0;
     while (raw &&
         typeof raw === "object" &&
         "configuration" in raw &&
         typeof raw.configuration === "object") {
         raw = raw.configuration;
+        levels++;
     }
+    // One level is the normal, expected shape signalk-server itself stores on disk (see the doc
+    // comment above) - only a *second* nested `configuration` key onwards is the corruption this
+    // guards against.
+    return { unwrapped: raw, wasNested: levels > 1 };
+}
+function pickKnownKeys(raw) {
     const result = {};
     if (raw && typeof raw === "object") {
         for (const key of PLUGIN_CONFIG_KEYS) {
@@ -83,6 +91,31 @@ function readCurrentConfig(app) {
     }
     return result;
 }
+function readCurrentConfig(app) {
+    const { unwrapped } = unwrapNestedConfiguration(app.readPluginOptions());
+    return pickKnownKeys(unwrapped);
+}
+/**
+ * Actively rewrites the on-disk file once it's nested (see `readCurrentConfig`'s doc comment) -
+ * `readCurrentConfig` alone only self-heals in memory for callers that go through it, but the admin
+ * UI's own config-editing form round-trips whatever raw JSON it was handed verbatim, including a
+ * stray nested `configuration` key it never touches (no schema field maps to it) - so left alone,
+ * every future save from the UI keeps re-persisting that dead weight forever (see
+ * `support/signalk-einklabel-plugin.json`). Called once at plugin start, which - unlike
+ * `clearForceRepaint` - isn't gated on any device having `forceRepaint` set, so a nested file gets
+ * flattened even if nothing ever triggers that path.
+ */
+function healNestedConfig(app) {
+    const { unwrapped, wasNested } = unwrapNestedConfiguration(app.readPluginOptions());
+    if (!wasNested)
+        return;
+    app.savePluginOptions(pickKnownKeys(unwrapped), (err) => {
+        if (err)
+            app.debug(`failed to clean up legacy nested plugin config: ${err.message}`);
+        else
+            app.debug("cleaned up a legacy nested plugin config file on disk");
+    });
+}
 /**
  * Resolves the user-facing `templatesDir` setting to an actual directory, mirroring
  * signalk-parquet's `outputDirectory` convention: empty means the default location, a relative

package/dist/plugin.js

@@ -49,6 +49,7 @@ function createPlugin(app) {
                 ...config,
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
+            (0, config_1.healNestedConfig)(app);
             if (pluginConfig.scanOnStart) {
                 void runStartupScan(app, pluginConfig.scanDurationSeconds);
             }

package/dist/repaintScheduler.js

@@ -234,11 +234,22 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     });
     const rawContext = await assembleRawContext(app, apiUrl, bindings);
     const templateHash = hashTemplate(templateMtimeMs);
+    // Hashed from `rawContext`, not `renderContext` below - `meta.repainted` (and the rest of `meta`)
+    // is only added after this point, deliberately, so a template merely *displaying* the repaint
+    // timestamp doesn't perpetually invalidate its own dedup and force a repaint every check. A full
+    // paint flashes the whole panel several times, and there's no confirmed partial-refresh path on
+    // these devices - so a bound value simply being unchanged is worth trusting over any staleness in
+    // a displayed clock.
     const dataHash = hashData(rawContext);
     const stateKey = stateKeyFor(device.friendlyName, address);
     const previous = state[stateKey];
     const templateChanged = previous?.templateHash !== templateHash;
     const dataChanged = previous?.dataHash !== dataHash;
+    // The devices are battery-constrained, so a repaint is skipped whenever neither the template nor
+    // the bound data has changed since the last successful paint - regardless of what triggered this
+    // check (interval or subscription) or whether it's a regular scheduled tick vs. the deferred
+    // startup catch-up (see `startupCheckTimer`). `forceRepaint` is the explicit, one-shot override
+    // for "repaint anyway".
     if (!templateChanged && !dataChanged && !device.forceRepaint) {
         app.debug(`${label}: data unchanged, skipping repaint`);
         return;

package/package.json

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