@rhizomatics/signalk-einklabel-plugin 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+# 0.8.0
+
+- New `settle` time, configurable and defaulting to 120 seconds, to wait after plugin startup before attempting to access paths
+  - First few minutes of a SignalK server startup can be a mess of plugins missing their dependencies and logging errors.
+- Schedule correctly picks up on previous schedule at startup, only repainting if the last scheduled time was overdue
+- Path based subscriptions ignore temporarily missing paths, so displays don't waste their tiny batteries on flapping values
+- Documentation now has a FAQ plus lots of other ESL/eInk hacking links.
+
+
 # 0.7.1
 
 - Fix path value retrieved for Image Fields when running in live plugin

package/README.md

@@ -7,7 +7,7 @@
 [![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)
 
-** Fully working but limited vendor/product support and requires Linux for device access **
+    Fully working but limited vendor/product support and requires Linux for device access.
 
 A SignalK plugin to display data from SignalK paths, APIs and plugins on Electronic Shelf Labels (ESL) over a Bluetooth Low Energy (BLE) connection using simple SVG templates.
 
@@ -48,7 +48,7 @@ Most of these requirements are about making SignalK work with Bluetooth Low Ener
 
 5. Correct time zone set on server if local time is to be shown on display
 
-- Use `raspi-config` on a Raspberry Pi, or `timedatectl` on a Linux server
+- See [FAQ](#faq-timezone)
 - If not set, everything will work, but you may see the wrong zone or not have daylight savings applied
 
 Once you have all of that, it may be worth also installing [signalk-victron-ble](https://github.com/stefanor/signalk-victron-ble) or [bt-sensors-plugin](https://github.com/naugehyde/bt-sensors-plugin-sk) to pull in data from other sensors and equipment.
@@ -83,7 +83,7 @@ Use the standard configuration option in the SignalK menu for the plugin.
 
 ![Plugin Configuration](docs/assets/screenshots/plugin_config.png)
 
-## Scanning for Devices
+### Scanning for Devices
 
 Since these are ultra-low power devices, they don't respond instantly to either identify themselves or accept a new image. By default, both scanning and painting have time-outs to wait for a response, which can be altered in the plugin configuration or CLI argument.
 
@@ -91,14 +91,17 @@ One other quirk is that some devices respond with a different name at different
 
 The plugin will optionally re-scan whenever it starts up, although this isn't essential once a label has been configured.
 
-### Scans from CLI
+### Scheduling
 
-The command line tools, run from inside the `.signalk` directory, can be used to help troubleshoot
+There are two ways of scheduling scans:
 
-- Scan for longer, in this example 90 seconds
-  - `npx esl-cli scan -d 90`
-- Scan for all BLE devices, whatever they are
-  - `npx esl-cli scan -a`
+#### Time Based
+
+This will schedule at fixed hours of the day, for example 00:00/08:00/16:00 for an 8h schedule, and at a selected minutes past the hour. At plugin startup/restart, the devices will be repainted if they missed their last slot.
+
+#### Path Subscription
+
+The devices will be painted when the plugin starts, and then every time the selected SignalK path changes.
 
 ## Templating
 
@@ -171,21 +174,6 @@ Three font types are loaded by default, use the generic font family, or exact fo
 - `sans-serif` - `Roboto`
 - `monospace` - `Roboto Mono`
 
-## Command Line Interface
-
-To get fast feedback on templates and shelf devices without updating and configuring SignalK, a CLI call `esl-cli` is provided when the module is manually installed that has these commands. Use `--help` to get all the options.
-
-- `vendors` - list supported vendors
-- `scan` - report supported devices found from a BLE scan
-
-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 is 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 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` )
 
 ## Vendors
 
@@ -214,6 +202,31 @@ The primary things managed and provided by the plugin are:
   - Optional: left blank, the plugin probes the probable values in likelihood order at startup - `http://localhost:3000`, `http://localhost`, `https://localhost`. Set it explicitly to skip probing
   - Either way, errors clearly if nothing responds (wrong port) or the probe is rejected (anonymous read access not enabled) - these endpoints must allow anonymous read access, since the plugin has no login flow
 
+## Command Line Interface
+
+To get fast feedback on templates and shelf devices without updating and configuring SignalK, a CLI call `esl-cli` is provided when the module is manually installed that has these commands. Use `--help` to get all the options.
+
+- `vendors` - list supported vendors
+- `scan` - report supported devices found from a BLE scan
+
+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 is 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 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` )
+
+### Scans from CLI
+
+The command line tools, run from inside the `.signalk` directory, can be used to help troubleshoot
+
+- Scan for longer, in this example 90 seconds
+  - `npx esl-cli scan -d 90`
+- Scan for all BLE devices, whatever they are
+  - `npx esl-cli scan -a`
+
 ## Extending
 
 ### Hardware
@@ -226,6 +239,8 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 ### Developing Templates
 
+See the [Templating] section for more details.
+
 Templates can be added to the configurable directory. [Inkscape](https://inkscape.org) free, open source, and recommended for editing templates, or your own favourite editor, or by hand in a text editor for hard core (or just tidying up the template side).
 
 ![Example Field Definition](docs/assets/screenshots/inkscape_desc.png)
@@ -238,6 +253,7 @@ Inkscape adds its own metadata to images, which can be stripped off by exporting
 
 Due to a limitation in the `resvg-wasm` library used to turn SVGs into images, the `font-family` is limited to `serif`,`sans-serif`,`monospace` or the exact name of one of the installed fonts - `Roboto` (sans serif), `Roboto Serif` or `Roboto Mono`. Inkscape has its own fonts, which won't match what's available in the SignalK plugin, so for more precise design, install [Roboto from Google](https://fonts.google.com/specimen/Roboto) via the web page, `brew` on MacOS or similar.
 
+
 ### Debugging Templates
 
 The `esl-cli` can be used to debug and validate templates quickly:
@@ -286,3 +302,38 @@ extremes.0.level         source=resources,resource=tides,path=extremes[0].level,
 - `categories.json` - SignalK unit categories needed for `category=depth` type formatting
 
 For example, `npx esl-cli fields -t templates/tide.svg -e examples` will show all the field data that will be populated from the example API, vessel and category data in the `examples` local directory.
+
+## Frequently Asked Questions
+
+### 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.
+
+Use the *settle* time, to impose a minimum wait between the eInk Label plugin being initialized, and it attempting to paint any displays, and increase this value if its still missing data.
+
+### Times are showing incorrectly {#faq-timezone}
+
+If times are in the wrong timezone, or don't have daylight savings applied correctly,
+then check that the server itself (at the Linux level, not SignalK, which doesn't know)is configured for your timezone, assuming of course that you're a coastal sailor. Use `raspi-config` on a Raspberry Pi, or `timedatectl` on a Linux server.
+
+If you're a global cruiser, then use something like [signalk-set-gps-timezone](https://github.com/hoeken/signalk-set-gps-timezone) to set the value in the operating system.
+
+### The ESL signal is too weak from my SignalK server
+
+Try a BLE proxy device, ESP32 is popular for this.
+
+## 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.
+- [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.
+- [hass-gicisky](https://github.com/eigger/hass-gicisky) - Home Assistant integration for Gicisky ESLs ( a similar vendor to Zhsunyco). Uses [imagespec](https://github.com/eigger/imagespec) for templating.
+- [ha-panda](https://github.com/moryoav/ha-panda) -  Home Assistant integration for Panda ESLs ( a similar vendor to Zhsunyco).
+- [Dmitry.gr](https://dmitry.gr/?r=05.Projects&proj=29.%20eInk%20Price%20Tags) - Personal site of an ESL hacker
+- [Aaron Christobel](https://www.youtube.com/@atc1441) - YouTube channel of an ESL hacker.
+- [rbaron.net](https://rbaron.net/blog/2022/07/29/Daisy-chaining-multiple-electronic-shelf-labels) - Blog of an early ESL hacker.
+- [Pimoroni](https://shop.pimoroni.com/collections/displays?tags=e-ink%20Displays) - All shapes and sizes of eInk displays, aimed at hackers, and with an [inky](https://github.com/pimoroni/inky) GitHub project to support them.
+- [WaveShare](https://www.waveshare.com/product/displays/e-paper.htm) - Wide range of eInk displays for hardware projects, not limited to ESLs.
+
+See also the [Boat Tech Directory](https://boat-tech-directory.rhizomatics.org.uk).

package/dist/config.d.ts

@@ -36,6 +36,15 @@ export interface PluginConfig {
     paintConnectTimeoutSeconds: number;
     /** How many times to attempt a repaint (including the first try) before giving up and reporting failure. */
     paintRetries: number;
+    /**
+     * How long after plugin start to hold off on every repaint trigger (startup check, interval, and
+     * subscription alike) - the first minute or two of a SignalK server's life is a chaos of plugin
+     * dependency sequencing (e.g. `derived-data` may not have published `environment.moon.phaseName`
+     * yet), so a repaint attempted immediately at startup can render with missing/wrong data, and hash
+     * dedup (see `considerRepaint`) then means it silently stays that way until the underlying data
+     * happens to change again. Defaults to 120s - see `startRepaintScheduler`.
+     */
+    settleSeconds: number;
     /**
      * Base URL of this SignalK server, used for: (1) a `signalk`-sourced numeric value's automatic unit
      * conversion (`GET .../vessels/<context>/meta`, see `../pathMeta.ts`) unless `format=raw`, and (2) an

package/dist/config.js

@@ -29,6 +29,7 @@ function defaultConfig() {
         scanDurationSeconds: 20,
         paintConnectTimeoutSeconds: 30,
         paintRetries: 3,
+        settleSeconds: 120,
         devices: [],
     };
 }
@@ -153,6 +154,15 @@ function configSchema(app, discovered = []) {
                 minimum: 1,
                 default: defaults.paintRetries,
             },
+            settleSeconds: {
+                type: "number",
+                title: "Settle time after plugin start (seconds)",
+                description: "Holds off every repaint (startup check, interval, and subscription alike) until this long after the plugin starts - " +
+                    "the first minute or two of SignalK startup is a chaos of plugin dependency sequencing, so data a template needs " +
+                    "(e.g. from the derived-data plugin) may not be published yet.",
+                minimum: 0,
+                default: defaults.settleSeconds,
+            },
             signalkApiUrl: {
                 type: "string",
                 title: "SignalK API base URL (leave blank to auto-detect)",

package/dist/render/svgRenderer.js

@@ -135,8 +135,8 @@ class SvgRenderer {
                     const dirProblem = (0, assets_1.describeAssetsDirProblem)(templatesDir, bundledTemplatesDir, binding.assets);
                     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 no usable value to pick an asset file with`);
-                    console.error(`${pluginVersion_1.PLUGIN_NAME}: ${dirProblem ?? `assets directory for "${binding.assets}" checked out fine - the miss is just this value's`}`);
+                        : `${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`}`);
                     element.parentNode?.removeChild(element);
                     continue;
                 }

package/dist/repaintScheduler.d.ts

@@ -3,4 +3,14 @@ import { PluginConfig } from "./config";
 export interface RepaintScheduler {
     stop(): void;
 }
+/**
+ * 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,
+ * at `intervalMinute` minutes past the hour (e.g. hours=8,minute=0 -> 00:00, 08:00, 16:00 each day).
+ * Used only by the deferred startup catch-up check to tell an interval device that's already been
+ * painted for its current slot (skip - the regular periodic check will catch the *next* slot in due
+ * course) from one that's overdue (e.g. the plugin was down across a scheduled slot - paint now
+ * rather than waiting up to `intervalHours` for the next one).
+ */
+export declare function mostRecentScheduledSlot(now: Date, intervalHours: number, intervalMinute: number): Date;
 export declare function startRepaintScheduler(app: ServerAPI, config: PluginConfig): RepaintScheduler;

package/dist/repaintScheduler.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mostRecentScheduledSlot = mostRecentScheduledSlot;
 exports.startRepaintScheduler = startRepaintScheduler;
 const crypto_1 = require("crypto");
 const path_1 = require("path");
@@ -17,6 +18,23 @@ const resolveApiUrl_1 = require("./resolveApiUrl");
 const pluginVersion_1 = require("./pluginVersion");
 const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
+/**
+ * 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,
+ * at `intervalMinute` minutes past the hour (e.g. hours=8,minute=0 -> 00:00, 08:00, 16:00 each day).
+ * Used only by the deferred startup catch-up check to tell an interval device that's already been
+ * painted for its current slot (skip - the regular periodic check will catch the *next* slot in due
+ * course) from one that's overdue (e.g. the plugin was down across a scheduled slot - paint now
+ * rather than waiting up to `intervalHours` for the next one).
+ */
+function mostRecentScheduledSlot(now, intervalHours, intervalMinute) {
+    const slot = new Date(now);
+    slot.setHours(Math.floor(now.getHours() / intervalHours) * intervalHours, intervalMinute, 0, 0);
+    if (slot.getTime() > now.getTime()) {
+        slot.setHours(slot.getHours() - intervalHours);
+    }
+    return slot;
+}
 function statePath(app) {
     return (0, path_1.join)(app.getDataDirPath(), "repaint-state.json");
 }
@@ -168,7 +186,7 @@ async function considerRepaint(app, config, device, state, getApiUrl) {
         await driver.paint(bitmap, { address: model.address, aesKey: device.aesKey, connectTimeoutMs });
         paintDurationMs = Date.now() - startedAt;
     });
-    state[device.friendlyName] = { hash };
+    state[device.friendlyName] = { hash, repaintedAt: Date.now() };
     saveState(app, state);
     if (device.forceRepaint) {
         clearForceRepaint(app, device.friendlyName);
@@ -179,7 +197,21 @@ function startRepaintScheduler(app, config) {
     const state = loadState(app);
     const unsubscribes = [];
     const getApiUrl = (0, resolveApiUrl_1.createApiUrlResolver)(config.signalkApiUrl);
-    const repaint = (device) => considerRepaint(app, config, device, state, getApiUrl).catch((err) => app.debug(`"${device.friendlyName}": repaint failed: ${err.message}`));
+    // The first minute or two of a SignalK server's life is a chaos of plugin dependency sequencing -
+    // a repaint attempted before other plugins (e.g. derived-data) have published the data a template
+    // needs renders with missing/wrong values, and hash dedup (see `considerRepaint`) then means it
+    // silently stays that way until the underlying data happens to change again. So every trigger
+    // (startup check, interval, subscription alike) funnels through this one gate.
+    const startedAt = Date.now();
+    const settleMs = (config.settleSeconds ?? 120) * 1000;
+    const repaint = (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 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) {
         const timer = setInterval(() => {
@@ -197,15 +229,43 @@ function startRepaintScheduler(app, config) {
     for (const device of config.devices) {
         if (device.repaintTrigger === "subscription" && device.triggerPath) {
             const stream = app.streambundle.getSelfStream(device.triggerPath).debounce(SUBSCRIPTION_DEBOUNCE_MS);
-            const unsub = stream.onValue(() => repaint(device));
+            // A path can report a transient `null`/missing value (e.g. a sensor briefly drops out) then go
+            // right back to what it was before - e.g. 1111, then missing, then 1111 again. Ignoring the
+            // missing emission entirely (rather than repainting for it) means it's never actually painted,
+            // so when the value comes back the same as before, `considerRepaint`'s hash dedup sees nothing
+            // changed since the last real paint and skips too - net effect: no repaint at all for this
+            // blip, instead of one flickering the display blank/wrong and a second restoring it.
+            const unsub = stream.onValue((value) => {
+                if (value !== null && value !== undefined)
+                    void repaint(device);
+            });
             unsubscribes.push(unsub);
         }
     }
-    // Check every device once at startup - harmless given hash dedup, and covers newly-added
-    // devices or a forceRepaint left set from before a restart.
-    for (const device of config.devices) {
-        void repaint(device);
-    }
+    // Check every device once, after the settle window. Deferred (rather than run immediately) so a
+    // subscription-triggered device whose path is slow-changing (e.g. tide/moon data that might not
+    // change again for hours) still gets its first real paint promptly once settled, instead of
+    // waiting on that path's next unrelated update - it's then left alone until the path changes
+    // again, same as always. An interval-triggered device, though, only gets this catch-up paint if
+    // 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.
+    const startupCheckTimer = setTimeout(() => {
+        for (const device of config.devices) {
+            if (device.repaintTrigger === "interval" && !device.forceRepaint) {
+                const hours = device.intervalHours ?? 1;
+                const minute = device.intervalMinute ?? 0;
+                const dueSlot = mostRecentScheduledSlot(new Date(), hours, minute);
+                const repaintedAt = state[device.friendlyName]?.repaintedAt;
+                if (repaintedAt !== undefined && repaintedAt >= dueSlot.getTime()) {
+                    app.debug(`"${device.friendlyName}": already painted for the current ${hours}h schedule slot - skipping startup catch-up`);
+                    continue;
+                }
+            }
+            void repaint(device);
+        }
+    }, settleMs);
+    unsubscribes.push(() => clearTimeout(startupCheckTimer));
     return {
         stop() {
             for (const unsubscribe of unsubscribes)

package/package.json

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