@rhizomatics/signalk-einklabel-plugin 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 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

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.

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/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/repaintScheduler.js

@@ -149,18 +149,21 @@ async function considerRepaint(app, config, device, state, getApiUrl) {
     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.3",
+  "version": "0.6.4",
   "description": "Display SignalK data on eInk Electronic Shelf Labels",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",