@rhizomatics/signalk-einklabel-plugin 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 0.6.4
+
+- Log improvements for device paint requests
+- CLI scan now shows `hwid`, and adds reason for failing to retrieve `battery` level
+
+# 0.6.3
+
+- Improve logging if an image cannot be found in an `assets` directory to match a SignalK path value
+- Expose `plugin_version` as a path for the `einklabel` source
+
 # 0.6.2
 
 - Auto default SignalK URL if `-u` or `-e` not passed as CLI arguments

package/README.md

@@ -7,7 +7,7 @@
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 [![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 **
+** 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.
 
@@ -25,7 +25,9 @@ Unlike some eInk projects, this plugin doesn't require any physical modification
 
 Most of these requirements are about making SignalK work with Bluetooth Low Energy, which is good thing to have anyway, since vendors like Victron, Switchbot, Ruuvi and others have BLE enabled hardware that's useful to have on a boat. [Direct BLE support](https://github.com/SignalK/signalk-server/issues/2411) in SignalK is being planned in 2026.
 
-1. A SignalK server, preferably running Linux (MacOS does weird things with bluetooth)
+1. A SignalK server, **running Linux**
+  - MacOS and Windows aren't supported by the [BLE interface layer](https://www.npmjs.com/package/@naugehyde/node-ble), however can be used for template development and
+  debugging (everything except `scan` and `paint`)
 2. A Bluetooth adapter, that can handle BLE (Bluetooth Low Energy), which is Bluetooth v4.0 or higher
 
 - Bluetooth adapters for Linux can be tricky, TP-Link UB400 and Asus USB-BT500 are two well-known and available ones
@@ -73,6 +75,24 @@ The tide clock needs the [signalk-tides](https://github.com/openwatersio/signalk
 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.
 
+## 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.
+
+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.
+
+### 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``` 
+
+
 ## Templating
 
 Templates are simply SVG files, to which expressions can be added to use SignalK data, with options to make it easier to read, like rounding or simplifying dates and times. The template can have sample data in the placeholder, so is easy to layout and visualize.
@@ -95,6 +115,7 @@ The source can be overridden to use the SignalK server's Resources API instead.
 
 - `path=repainted` - the timestamp of the current repaint - for example `source=einklabel,path=repainted,format=local_datetime_short` to show when the label was last updated.
 - `path=local_zone` - a short zone name (e.g. `BST`) for the same timezone used for `local_time`/`day_mon`/`local_datetime_short` (see above) - a fallback for `environment.time.timezoneRegion,format=utc_offset` on installs that never publish that path, since it needs no SignalK metadata of its own. Falls back to a plain UTC offset like `GMT+1` where the host's locale has no real abbreviation for the zone.
+- `path=plugin_version` - expose the version of the eInk Label plugin itself.
 
 #### Customizing Output
 

package/dist/cli/index.js

@@ -114,7 +114,7 @@ program
     .option('-a, --all-devices', "list every nearby BLE device, not just ones a registered driver recognised - unmatched devices show address/name/mfr/rssi only, since there's no driver to do a vendor-specific read like battery")
     .action(async (opts) => {
     const durationMs = Number(opts.duration) * 1000;
-    const header = ['vendor', 'address', 'name', 'pid', 'label', 'mfr', 'battery', 'rssi'];
+    const header = ['vendor', 'address', 'name', 'pid', 'hwid', 'label', 'mfr', 'battery', 'rssi'];
     const rows = [];
     let matchedCount = 0;
     const drivers = (0, registry_1.allDrivers)();
@@ -129,7 +129,7 @@ program
                         .getRSSI()
                         .then((value) => (value === undefined ? undefined : Number(value)))
                         .catch(() => undefined);
-                    rows.push(['(unmatched)', address, name ?? '', '', '', mfr, '', String(rssi ?? '')]);
+                    rows.push(['(unmatched)', address, name ?? '', '', '', '', mfr, '', String(rssi ?? '')]);
                 }
                 return;
             }
@@ -137,9 +137,10 @@ program
             const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData);
             (0, log_1.logDebug)(`${driver.vendor}: identified ${found.name ?? found.address}`);
             const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, '0')}` : '';
+            const hwid = found.hwVersion ? `0x${found.hwVersion}` : '';
             const label = found.metadata?.label ?? '';
             const battery = found.batteryMv !== undefined ? `${found.batteryMv}mV` : '';
-            rows.push([driver.vendor, found.address, found.name ?? '', pid, label, mfr, battery, String(found.rssi ?? '')]);
+            rows.push([driver.vendor, found.address, found.name ?? '', pid, hwid, label, mfr, battery, String(found.rssi ?? '')]);
         });
     });
     if (matchedCount === 0) {
@@ -192,7 +193,7 @@ program
     const connectTimeoutMs = Number(opts.connectTimeout) * 1000;
     await (0, bleDiscovery_1.withRetries)(Number(opts.retries), async (attempt) => {
         if (attempt > 1) {
-            (0, log_1.logDebug)(`paint attempt ${attempt}/${opts.retries}`);
+            (0, log_1.logDebug)(`Attempting paint ${attempt}/${opts.retries}`);
         }
         await driver.paint(bitmap, { address: opts.address, aesKey: opts.aesKey, modelOverride, connectTimeoutMs });
     });

package/dist/cli/liveContext.js

@@ -11,6 +11,7 @@ const formatters_1 = require("../render/formatters");
 const httpJson_1 = require("../httpJson");
 const unitCategories_1 = require("../unitCategories");
 const pathMeta_1 = require("../pathMeta");
+const pluginVersion_1 = require("../pluginVersion");
 const log_1 = require("./log");
 const RESOURCES_API_PATH = '/signalk/v2/api/resources';
 /** `context=self` -> `vessels/self`, `context=vessels.urn:mrn:imo:mmsi:1` -> `vessels/urn:mrn:imo:mmsi:1` - matches the REST path for that context's full-data-model subtree. */
@@ -78,7 +79,11 @@ async function assembleLiveContext(signalkUrl, bindings) {
     const categories = await (0, unitCategories_1.fetchCategoryDisplayUnits)(signalkUrl, categoryNames);
     // Matches `considerRepaint` in repaintScheduler.ts - the CLI has no real device repaint to time, so
     // a `source=einklabel,path=repainted` binding just resolves to "now", same as a live render would.
-    const meta = { repainted: new Date().toISOString(), local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)({ signalk }) };
+    const meta = {
+        repainted: new Date().toISOString(),
+        local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)({ signalk }),
+        plugin_version: pluginVersion_1.PLUGIN_VERSION,
+    };
     return { signalk, resources, pathMeta, categories, meta };
 }
 async function readJsonFile(filePath) {
@@ -147,6 +152,10 @@ async function assembleExampleContext(examplesDir, bindings) {
             }
         }
     }
-    const meta = { repainted: new Date().toISOString(), local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)({ signalk }) };
+    const meta = {
+        repainted: new Date().toISOString(),
+        local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)({ signalk }),
+        plugin_version: pluginVersion_1.PLUGIN_VERSION,
+    };
     return { signalk, resources, pathMeta: {}, categories, meta };
 }

package/dist/devices/zhsunyco/index.js

@@ -31,7 +31,7 @@ class ZhsunycoDriver {
     }
     async identifyDevice(device, address, name, manufacturerId, manufacturerData) {
         const advertisedInfo = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
-        const { info, batteryMv } = await readDeviceDetails(device, advertisedInfo);
+        const { info, batteryMv } = await readDeviceDetails(device, address, advertisedInfo);
         return {
             address,
             name,
@@ -113,7 +113,7 @@ exports.ZhsunycoDriver = ZhsunycoDriver;
  * config characteristic `paint()` reads, just to identify the device rather than to size a
  * render.
  */
-async function readDeviceDetails(device, advertisedInfo) {
+async function readDeviceDetails(device, address, advertisedInfo) {
     const fallback = { info: advertisedInfo, batteryMv: undefined };
     const read = async () => {
         try {
@@ -134,7 +134,12 @@ async function readDeviceDetails(device, advertisedInfo) {
                 await device.disconnect();
             }
         }
-        catch {
+        catch (err) {
+            // Swallowed rather than thrown - a device that refuses this connect (e.g. busy elsewhere,
+            // out of range) should still show up in the scan with whatever the advertisement itself
+            // carried, just without battery/PID-by-read. Logged so a blank battery column has a reason
+            // instead of looking like the read was simply never attempted.
+            console.error(`zhsunyco [${address}]: battery/config read failed: ${err.message}`);
             return fallback;
         }
     };
@@ -142,5 +147,11 @@ async function readDeviceDetails(device, advertisedInfo) {
     // `getPrimaryService`/`readValue`) has no timeout of its own either - race the whole read so
     // one unresponsive device can't stall the rest of the scan (see `plugin.ts`'s `scanInProgress`,
     // 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(() => fallback)]);
+    return Promise.race([
+        read(),
+        (0, bleDiscovery_1.sleep)(SCAN_CONNECT_TIMEOUT_MS * 2).then(() => {
+            console.error(`zhsunyco [${address}]: battery/config read timed out after ${SCAN_CONNECT_TIMEOUT_MS * 2}ms`);
+            return fallback;
+        }),
+    ]);
 }

package/dist/plugin.js

@@ -29,7 +29,8 @@ async function runStartupScan(app, discovered, durationSeconds) {
                 }
                 discovered.push(found);
                 const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, '0')}` : 'unknown';
-                app.debug(`discovered ${driver.vendor} device "${found.name ?? ''}" [${found.address}] pid=${pid}`);
+                const hwid = found.hwVersion ?? 'unknown';
+                app.debug(`discovered ${driver.vendor} device "${found.name ?? ''}" [${found.address}] pid=${pid} hwid=${hwid}`);
             });
         });
     }

package/dist/pluginVersion.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The installed plugin's own version, read from `package.json` once at module load - exposed to
+ * templates as `source=einklabel,path=plugin_version` (see `meta` in repaintScheduler.ts and
+ * `cli/liveContext.ts`), e.g. to show a build/version marker on a label for support purposes.
+ */
+export declare const PLUGIN_VERSION: string;

package/dist/pluginVersion.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_VERSION = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * The installed plugin's own version, read from `package.json` once at module load - exposed to
+ * templates as `source=einklabel,path=plugin_version` (see `meta` in repaintScheduler.ts and
+ * `cli/liveContext.ts`), e.g. to show a build/version marker on a label for support purposes.
+ */
+exports.PLUGIN_VERSION = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', 'package.json'), 'utf-8')).version;

package/dist/render/svgRenderer.js

@@ -128,6 +128,9 @@ class SvgRenderer {
                 const key = (0, assets_1.normalizeAssetKey)((0, binding_1.resolveBinding)(binding, context));
                 const assetPath = key && (0, assets_1.resolveAssetPath)(svgTemplatePath, binding.assets, key);
                 if (!assetPath) {
+                    console.error(key
+                        ? `image "${descElement.textContent}" has no asset file for value "${key}" in "${binding.assets}"`
+                        : `image "${descElement.textContent}" resolved to no usable value to pick an asset file with`);
                     element.parentNode?.removeChild(element);
                     continue;
                 }

package/dist/repaintScheduler.js

@@ -13,6 +13,7 @@ const formatters_1 = require("./render/formatters");
 const unitCategories_1 = require("./unitCategories");
 const pathMeta_1 = require("./pathMeta");
 const resolveApiUrl_1 = require("./resolveApiUrl");
+const pluginVersion_1 = require("./pluginVersion");
 const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
 function statePath(app) {
@@ -139,23 +140,30 @@ async function considerRepaint(app, config, device, state, getApiUrl) {
     }
     const renderContext = {
         ...rawContext,
-        meta: { repainted: new Date().toISOString(), local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)(rawContext) },
+        meta: {
+            repainted: new Date().toISOString(),
+            local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)(rawContext),
+            plugin_version: pluginVersion_1.PLUGIN_VERSION,
+        },
     };
     const renderer = new svgRenderer_1.SvgRenderer();
     const bitmap = await renderer.render(templatePath, renderContext, metadata.width, metadata.height - metadata.voffset);
     const connectTimeoutMs = config.paintConnectTimeoutSeconds * 1000;
+    let paintDurationMs = 0;
     await (0, bleDiscovery_1.withRetries)(config.paintRetries, async (attempt) => {
         if (attempt > 1) {
-            app.debug(`"${device.friendlyName}": paint attempt ${attempt}/${config.paintRetries}`);
+            app.debug(`"${device.friendlyName}": attempting paint ${attempt}/${config.paintRetries}`);
         }
+        const startedAt = Date.now();
         await driver.paint(bitmap, { address: model.address, aesKey: device.aesKey, connectTimeoutMs });
+        paintDurationMs = Date.now() - startedAt;
     });
     state[device.friendlyName] = { hash };
     saveState(app, state);
     if (device.forceRepaint) {
         clearForceRepaint(app, device.friendlyName);
     }
-    app.debug(`"${device.friendlyName}": repainted`);
+    app.debug(`"${device.friendlyName}": repainted (paint took ${paintDurationMs}ms)`);
 }
 function startRepaintScheduler(app, config) {
     const state = loadState(app);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Display SignalK data on eInk Electronic Shelf Labels",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/templates/tide.svg

@@ -23,8 +23,8 @@
      inkscape:pagecheckerboard="0"
      inkscape:deskcolor="#d1d1d1"
      inkscape:zoom="1.3906433"
-     inkscape:cx="249.88435"
-     inkscape:cy="101.03238"
+     inkscape:cx="144.89697"
+     inkscape:cy="197.39066"
      inkscape:window-width="1488"
      inkscape:window-height="674"
      inkscape:window-x="24"
@@ -71,19 +71,19 @@
      transform="scale(0.89274878,1.1201359)">Tidal Station Name<desc
    id="desc1">source=resources,resource=tides,path=station.name</desc></text><text
      id="source"
-     x="347.95166"
+     x="367.44577"
      y="226.1548"
      font-size="18"
      font-family="serif"
      fill="black"
-     style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3333px;font-family:sans-serif;-inkscape-font-specification:'Roboto',sans-serif;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#ff0000;stroke-width:3.80045"
-     transform="scale(0.95907863,1.0426674)"><desc
+     style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3333px;font-family:sans-serif;-inkscape-font-specification:'\'Roboto\', sans-serif';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#ff0000;stroke-width:3.80045"
+     transform="scale(0.95907862,1.0426674)"><desc
        id="desc21">source=resources,resource=tides,path=station.source.name</desc><tspan
        sodipodi:role="line"
        id="tspan20"
-       x="347.95166"
+       x="367.44577"
        y="226.1548"
-       style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3332995px;font-family:sans-serif;-inkscape-font-specification:'Roboto',sans-serif;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;stroke-width:3.80045">SOURCE</tspan></text><text
+       style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3333px;font-family:sans-serif;-inkscape-font-specification:'\'Roboto\', sans-serif';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;stroke-width:3.80045">SOURCE</tspan></text><text
      id="last_repaint"
      x="4.3477793"
      y="201.9895"
@@ -119,8 +119,8 @@
      fill="red"
      style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:22.6667px;font-family:sans-serif;-inkscape-font-specification:'Roboto, Normal',sans-serif;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#ff0000"><desc
    id="desc15">source=resources,resource=tides,path=extremes[2].label</desc>High or Low</text><text
-     id="environment.time.timezoneRegion"
-     x="239.09819"
+     id="timezone"
+     x="330.60489"
      y="204.67754"
      font-size="10.373px"
      font-family="sans-serif"
@@ -128,7 +128,20 @@
      style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3333px;font-family:sans-serif;-inkscape-font-specification:'Roboto, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;direction:rtl;fill:#000000;stroke-width:0.864419"
      transform="scale(0.86441854,1.156847)">UTC+01:00<desc
    id="desc11">source=einklabel,path=local_zone</desc></text><text
-     id="lat"
+     id="plugin_version"
+     x="194.07487"
+     y="204.51942"
+     font-size="10.373px"
+     font-family="sans-serif"
+     fill="#ffff00"
+     style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:13.3333px;font-family:Roboto;-inkscape-font-specification:'Roboto, Normal';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;direction:rtl;fill:#000000;stroke-width:0.864419"
+     transform="scale(0.86441854,1.156847)"><desc
+       id="desc16">source=einklabel,path=plugin_version</desc><tspan
+       sodipodi:role="line"
+       id="tspan1"
+       x="194.07487"
+       y="204.51942">v0.0.1</tspan></text><text
+     id="min_tide"
      x="282.65424"
      y="24.967674"
      font-size="12px"
@@ -140,7 +153,7 @@
        id="tspan17"
        x="282.65424"
        y="24.967674">0.0m</tspan></text><text
-     id="hat"
+     id="max_tide"
      x="360.77148"
      y="24.967674"
      font-size="12px"
@@ -211,7 +224,7 @@
      style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:37.3333px;font-family:monospace;-inkscape-font-specification:'Roboto Mono, Bold',monospace;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#000000;stroke-width:1.55397"
      transform="scale(0.74654856,1.3394976)">03:27<desc
    id="desc3">source=resources,resource=tides,path=extremes[0].time,format=local_time</desc></text><text
-     id="extremes.0.time-8"
+     id="extremes.0.date"
      x="10.326324"
      y="74.630478"
      font-size="14"
@@ -220,7 +233,7 @@
      style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:22.6667px;font-family:sans-serif;-inkscape-font-specification:'Roboto, Normal',sans-serif;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#666666;stroke-width:1.32646"
      transform="scale(0.82428216,1.2131768)"><desc
    id="desc2">source=resources,resource=tides,path=extremes[0].time,format=day_mon</desc>27 Jun</text><text
-     id="extremes.0.time-8-5"
+     id="extremes.1.date"
      x="9.9649849"
      y="123.34451"
      font-size="14"
@@ -229,7 +242,7 @@
      style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:22.6667px;font-family:sans-serif;-inkscape-font-specification:'Roboto, Normal',sans-serif;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-variant-east-asian:normal;fill:#666666;stroke-width:1.32646"
      transform="scale(0.82428216,1.2131768)"><desc
    id="desc7">source=resources,resource=tides,path=extremes[1].time,format=day_mon</desc>27 Jun</text><text
-     id="extremes.0.time-8-9"
+     id="extremes.2.date"
      x="12.934491"
      y="156.77794"
      font-size="14"