@rhizomatics/signalk-einklabel-plugin 0.6.3 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 0.7.0
+
+## Logging
+
+- Standardize all log output to show a `signalk-einklabel-plugin` prefix
+
+## Image Fields
+
+- Include image fields on CLI `fields` command output
+- Better logging diagnostics if asset image resolution fails or directory not found
+- Replace separate fixed `resources/svg` directory for images with user overridable `templates/assets`
+  - Means that the bundled lunar phase icons can be easily replaced without touching the template - use the same file names in `templates/assets/lunar_phases` directory.
+  - Added attribution to the Lunar Phases icons
+
+## Build
+
+- Added `pre-commit`, `oxlint` and `oxfmt` for code quality, retired `prettier`
+
+# 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

@@ -4,10 +4,10 @@
 [![npm downloads](https://img.shields.io/npm/dm/@rhizomatics/signalk-einklabel-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-einklabel-plugin)
 [![SignalK Plugin CI](https://github.com/rhizomatics/signalk-einklabel-plugin/actions/workflows/signalk-ci.yml/badge.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/actions/workflows/signalk-ci.yml)
 [![codecov](https://img.shields.io/codecov/c/github/rhizomatics/signalk-einklabel-plugin)](https://codecov.io/gh/rhizomatics/signalk-einklabel-plugin)
-[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![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 **
+** 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,11 @@ 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 +77,29 @@ 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.
 
+## Configuration
+
+Use the standard configuration option in the SignalK menu for the plugin.
+
+![Plugin Configuration](docs/assets/screenshots/plugin_config.png)
+
+## 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.
@@ -124,15 +151,17 @@ These can all be combined as in `source=resources,resource=tides,path=extremes[2
 
 ### Non-Textual Fields (Images)
 
-The same `<desc>` mechanism works on an `<image>` element instead of a `<text>` element, for a value that's better shown as a picture than as text - a moon phase icon, a wind direction arrow, a weather condition glyph, and so on. Rather than substituting text, the resolved value picks one of a directory of `.svg` files to embed, by an extra required `assets=` key naming that directory (resolved relative to the template file itself, so a bundled template and a user override both work the same way). For example, the tide clock's moon phase icon uses:
+The same `<desc>` mechanism works on an `<image>` element instead of a `<text>` element, for a value that's better shown as a picture than as text - a moon phase icon, a wind direction arrow, a weather condition glyph, and so on. Rather than substituting text, the resolved value picks one of a directory of `.svg` files to embed, by an extra required `assets=` key naming that directory - an `assets/<name>` sub-directory looked up in your configured `templates` directory first, and the bundled `templates` directory otherwise. For example, the tide clock's moon phase icon uses:
 
 ```
-path=environment.moon.phaseName,assets=../resources/svg/lunar_phases
+path=environment.moon.phaseName,assets=lunar_phases
 ```
 
-The resolved value (e.g. `"Waning Gibbous"`, as published by the [derived-data](https://www.npmjs.com/package/signalk-derived-data) plugin) is normalized to match a filename - lower-cased, punctuation and spaces collapsed to underscores - so `"Waning Gibbous"` picks `waning_gibbous.svg` out of that directory. If the underlying path has no value at all (e.g. the `derived-data` plugin isn't installed), or the value doesn't normalize to any file in the directory, the `<image>` element is simply omitted from that render - no broken image, no placeholder, nothing shown.
+which resolves against `templates/assets/lunar_phases/` (bundled, or your own configured `templates` directory's `assets/lunar_phases/` if you have one). The resolved value (e.g. `"Waning Gibbous"`, as published by the [derived-data](https://www.npmjs.com/package/signalk-derived-data) plugin) is normalized to match a filename - lower-cased, punctuation and spaces collapsed to underscores - so `"Waning Gibbous"` picks `waning_gibbous.svg` out of that directory. If the underlying path has no value at all (e.g. the `derived-data` plugin isn't installed), or the value doesn't normalize to any file in the directory, the `<image>` element is omitted from that render - no broken image, no placeholder, nothing shown - and a line is logged to the console so a missing/unmatched value isn't silently invisible.
+
+If you don't like the bundled moon phase icons, save your own `<value>.svg` files in the `assets/lunar_phases` sub-directory of your configured `templates` directory - the whole directory is used in place of the bundled one, so add all 8 phases you want to keep, not just the ones you're changing.
 
-This is a general mechanism, not specific to moon phases - any `source`/`context`/`path`/`format` combination valid for a `<text>` binding works here too (a `source=resources` value, an explicit `category=`, etc.), the only difference is the required `assets=` directory and the "no match -> no image" behaviour instead of substituted text. To add your own, put a directory of `<value>.svg` files somewhere relative to your template, add an `<image>` element in your SVG editor at the size/position you want, and give it a `<desc>` the same way you would a text field.
+This is a general mechanism, not specific to moon phases - any `source`/`context`/`path`/`format` combination valid for a `<text>` binding works here too (a `source=resources` value, an explicit `category=`, etc.), the only difference is the required `assets=` directory and the "no match -> no image" behaviour instead of substituted text. To add your own, put a directory of `<value>.svg` files under an `assets/<name>` sub-directory of your `templates` directory, add an `<image>` element in your SVG editor at the size/position you want, and give it a `<desc>` the same way you would a text field - overriding just the template, just its assets, or both together, all work independently.
 
 ### Fonts
 
@@ -199,7 +228,7 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 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/inkscape_desc.png)
+![Example Field Definition](docs/assets/screenshots/inkscape_desc.png)
 
 The object ID and label aren't used by the plugin, only the description is used to define fields. You can also add in ordinary text fields without field definitions, as labels, logos, help text etc.
 

package/dist/cli/index.js

@@ -2,6 +2,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const promises_1 = require("fs/promises");
+const path_1 = require("path");
 const commander_1 = require("commander");
 const xmldom_1 = require("@xmldom/xmldom");
 const registry_1 = require("../devices/registry");
@@ -10,22 +11,24 @@ const bleDiscovery_1 = require("../devices/bleDiscovery");
 const svgRenderer_1 = require("../render/svgRenderer");
 const png_1 = require("../render/png");
 const binding_1 = require("../render/binding");
+const assets_1 = require("../render/assets");
+const config_1 = require("../config");
 const liveContext_1 = require("./liveContext");
 const httpJson_1 = require("../httpJson");
 const log_1 = require("./log");
 (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
 const VENDOR_IDENTIFY_TIMEOUT_MS = 30000;
 /** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
-const DEFAULT_SIGNALK_URLS = ['http://localhost', 'http://localhost:3000', 'https://localhost'];
+const DEFAULT_SIGNALK_URLS = ["http://localhost", "http://localhost:3000", "https://localhost"];
 const COLOUR_CODES = {
-    BW: ['black', 'white'],
-    BWR: ['black', 'white', 'red'],
-    BWRY: ['black', 'white', 'red', 'yellow'],
+    BW: ["black", "white"],
+    BWR: ["black", "white", "red"],
+    BWRY: ["black", "white", "red", "yellow"],
 };
 function parseColours(code) {
     const colours = COLOUR_CODES[code.toUpperCase()];
     if (!colours) {
-        throw new Error(`unknown --colours value "${code}" - expected one of ${Object.keys(COLOUR_CODES).join(', ')}`);
+        throw new Error(`unknown --colours value "${code}" - expected one of ${Object.keys(COLOUR_CODES).join(", ")}`);
     }
     return colours;
 }
@@ -41,7 +44,7 @@ async function resolveDefaultUrl() {
             (0, log_1.logDebug)(`${candidate} did not answer: ${err.message}`);
         }
     }
-    throw new Error(`no -u/--url given and none of ${DEFAULT_SIGNALK_URLS.join(', ')} answered - specify the server explicitly with -u/--url`);
+    throw new Error(`no -u/--url given and none of ${DEFAULT_SIGNALK_URLS.join(", ")} answered - specify the server explicitly with -u/--url`);
 }
 /** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
 async function assembleContext(opts, bindings) {
@@ -59,7 +62,7 @@ async function identifyVendor(address) {
         const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, address, VENDOR_IDENTIFY_TIMEOUT_MS);
         const name = await device.getName().catch(() => undefined);
         const manufacturerId = await (0, bleDiscovery_1.getManufacturerId)(device);
-        (0, log_1.logDebug)(`${address}: advertised name="${name ?? ''}" manufacturerId=${manufacturerId ?? 'unknown'}`);
+        (0, log_1.logDebug)(`${address}: advertised name="${name ?? ""}" manufacturerId=${manufacturerId ?? "unknown"}`);
         const driver = (0, registry_1.allDrivers)().find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
         if (!driver) {
             throw new Error(`no registered vendor driver recognises device "${name ?? address}" - specify --vendor explicitly`);
@@ -71,50 +74,54 @@ async function identifyVendor(address) {
     }
 }
 const program = new commander_1.Command();
-program.name('esl-cli').description('Local CLI for testing ESL device scan and paint without a SignalK server');
-program.option('-r, --require <module>', 'require a module before running, e.g. an npm package that registers a vendor driver (repeatable)', (value, previous = []) => [...previous, value]);
-program.option('-l, --log-level <level>', 'log verbosity: info or debug (e.g. trace which URLs are fetched)', 'info');
-program.hook('preAction', () => {
+program.name("esl-cli").description("Local CLI for testing ESL device scan and paint without a SignalK server");
+program.option("-r, --require <module>", "require a module before running, e.g. an npm package that registers a vendor driver (repeatable)", 
+// Commander's own typings declare `previous` as always `string[]`, but at runtime it's actually
+// `undefined` on the first invocation when no default is passed to `.option()` - the `| undefined`
+// here keeps that true and makes the `= []` fallback meaningful rather than dead code.
+(value, previous = []) => [...previous, value]);
+program.option("-l, --log-level <level>", "log verbosity: info or debug (e.g. trace which URLs are fetched)", "info");
+program.hook("preAction", () => {
     (0, log_1.setLogLevel)(program.opts().logLevel);
     for (const mod of program.opts().require ?? []) {
         require(mod);
     }
 });
 program
-    .command('vendors')
-    .description('List supported vendors and the device models each has confirmed metadata for')
+    .command("vendors")
+    .description("List supported vendors and the device models each has confirmed metadata for")
     .action(() => {
-    const header = ['vendor', 'pid', 'hwid', 'label', 'size', 'colours'];
+    const header = ["vendor", "pid", "hwid", "label", "size", "colours"];
     const rows = [];
     for (const driver of (0, registry_1.allDrivers)()) {
         for (const device of driver.supportedDevices()) {
             rows.push([
                 driver.vendor,
-                `0x${device.pid.toString(16).padStart(4, '0')}`,
-                device.hwVersion ? `0x${device.hwVersion}` : '',
+                `0x${device.pid.toString(16).padStart(4, "0")}`,
+                device.hwVersion ? `0x${device.hwVersion}` : "",
                 device.label,
                 `${device.width}x${device.height}`,
-                device.colours.join(','),
+                device.colours.join(","),
             ]);
         }
     }
     if (rows.length === 0) {
-        console.log('(no confirmed devices yet)');
+        console.log("(no confirmed devices yet)");
         return;
     }
     const widths = header.map((title, col) => Math.max(title.length, ...rows.map((row) => row[col].length)));
-    const printRow = (row) => console.log(row.map((cell, col) => cell.padEnd(widths[col])).join('  '));
+    const printRow = (row) => console.log(row.map((cell, col) => cell.padEnd(widths[col])).join("  "));
     printRow(header);
     rows.forEach(printRow);
 });
 program
-    .command('scan')
-    .description('Scan for supported BLE ESL devices across all registered vendor drivers')
-    .option('-d, --duration <seconds>', 'scan duration in seconds', '10')
-    .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")
+    .command("scan")
+    .description("Scan for supported BLE ESL devices across all registered vendor drivers")
+    .option("-d, --duration <seconds>", "scan duration in seconds", "10")
+    .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)();
@@ -122,24 +129,25 @@ program
     await (0, bleDiscovery_1.withDiscovery)(durationMs, async (adapter) => {
         await (0, bleDiscovery_1.forEachAdvertisedDevice)(adapter, async ({ device, address, name, manufacturerId, manufacturerData }) => {
             const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
-            const mfr = manufacturerId !== undefined ? `0x${manufacturerId.toString(16).padStart(4, '0')}` : '';
+            const mfr = manufacturerId !== undefined ? `0x${manufacturerId.toString(16).padStart(4, "0")}` : "";
             if (!driver) {
                 if (opts.allDevices) {
                     const rssi = await device
                         .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;
             }
             matchedCount++;
             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 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 ?? '')]);
+            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, hwid, label, mfr, battery, String(found.rssi ?? "")]);
         });
     });
     if (matchedCount === 0) {
@@ -149,27 +157,27 @@ program
         return;
     }
     const widths = header.map((title, col) => Math.max(title.length, ...rows.map((row) => row[col].length)));
-    const printRow = (row) => console.log(row.map((cell, col) => cell.padEnd(widths[col])).join('  '));
+    const printRow = (row) => console.log(row.map((cell, col) => cell.padEnd(widths[col])).join("  "));
     printRow(header);
     rows.forEach(printRow);
 });
 program
-    .command('paint')
-    .description('Render a template against a live SignalK server and send it to a device')
-    .option('-v, --vendor <vendor>', "vendor driver to use - if omitted, inferred from the device's advertised name")
-    .requiredOption('-a, --address <address>', 'BLE address of the device')
-    .requiredOption('-t, --template <path>', 'path to SVG template')
-    .option('-u, --url <url>', "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(', ') +
-    ' in turn')
-    .option('-e, --example-data <dir>', 'load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u')
-    .option('-k, --aes-key <hex>', "AES-128 key for device authentication, as 32 hex characters - defaults to the vendor's stock key if omitted")
-    .option('-w, --width <px>', 'render width', '416')
-    .option('--height <px>', 'render height', '240')
-    .option('--voffset <px>', 'vertical pixel offset of the panel - overrides the looked-up model for unsupported hardware (requires --colours)', '0')
-    .option('--colours <code>', 'device colour palette for unsupported hardware: BW, BWR, or BWRY - overrides the looked-up model (uses --width/--height/--voffset)')
-    .option('--connect-timeout <seconds>', 'BLE connect timeout before giving up on an attempt', '30')
-    .option('--retries <n>', 'number of paint attempts (including the first) before giving up', '3')
+    .command("paint")
+    .description("Render a template against a live SignalK server and send it to a device")
+    .option("-v, --vendor <vendor>", "vendor driver to use - if omitted, inferred from the device's advertised name")
+    .requiredOption("-a, --address <address>", "BLE address of the device")
+    .requiredOption("-t, --template <path>", "path to SVG template")
+    .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
+    DEFAULT_SIGNALK_URLS.join(", ") +
+    " in turn")
+    .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
+    .option("-k, --aes-key <hex>", "AES-128 key for device authentication, as 32 hex characters - defaults to the vendor's stock key if omitted")
+    .option("-w, --width <px>", "render width", "416")
+    .option("--height <px>", "render height", "240")
+    .option("--voffset <px>", "vertical pixel offset of the panel - overrides the looked-up model for unsupported hardware (requires --colours)", "0")
+    .option("--colours <code>", "device colour palette for unsupported hardware: BW, BWR, or BWRY - overrides the looked-up model (uses --width/--height/--voffset)")
+    .option("--connect-timeout <seconds>", "BLE connect timeout before giving up on an attempt", "30")
+    .option("--retries <n>", "number of paint attempts (including the first) before giving up", "3")
     .action(async (opts) => {
     const vendor = opts.vendor ?? (await identifyVendor(opts.address));
     const driver = (0, registry_1.getDriver)(vendor);
@@ -178,96 +186,122 @@ program
     }
     const modelOverride = opts.colours
         ? {
-            label: 'manual override',
+            label: "manual override",
             width: Number(opts.width),
             height: Number(opts.height),
             voffset: Number(opts.voffset),
             colours: parseColours(opts.colours),
         }
         : undefined;
-    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, 'utf-8'));
+    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, "utf-8"));
     const context = await assembleContext(opts, bindings);
     const renderer = new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height));
+    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height), (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
     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 });
+        await driver.paint(bitmap, {
+            address: opts.address,
+            aesKey: opts.aesKey,
+            modelOverride,
+            connectTimeoutMs,
+        });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
 });
 program
-    .command('render')
-    .description('Render a template against a live SignalK server and write a PNG, without needing a device')
-    .requiredOption('-t, --template <path>', 'path to SVG template')
-    .requiredOption('-o, --output <path>', 'output PNG path')
-    .option('-u, --url <url>', "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(', ') +
-    ' in turn')
-    .option('-e, --example-data <dir>', 'load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u')
-    .option('-w, --width <px>', 'render width', '416')
-    .option('--height <px>', 'render height', '240')
-    .option('-f, --font <path>', 'override a bundled font with this file (repeatable) - defaults to the bundled monospace/sans-serif/serif trio', (value, previous = []) => [...previous, value])
+    .command("render")
+    .description("Render a template against a live SignalK server and write a PNG, without needing a device")
+    .requiredOption("-t, --template <path>", "path to SVG template")
+    .requiredOption("-o, --output <path>", "output PNG path")
+    .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
+    DEFAULT_SIGNALK_URLS.join(", ") +
+    " in turn")
+    .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
+    .option("-w, --width <px>", "render width", "416")
+    .option("--height <px>", "render height", "240")
+    .option("-f, --font <path>", "override a bundled font with this file (repeatable) - defaults to the bundled monospace/sans-serif/serif trio", 
+// See the -r/--require option above for why `| undefined` is needed here despite commander's typings.
+(value, previous = []) => [...previous, value])
     .action(async (opts) => {
-    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, 'utf-8'));
+    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, "utf-8"));
     const context = await assembleContext(opts, bindings);
     const renderer = opts.font ? new svgRenderer_1.SvgRenderer(opts.font) : new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height));
+    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height), (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
     await (0, promises_1.writeFile)(opts.output, (0, png_1.bitmapToPng)(bitmap));
     console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})`);
 });
 program
-    .command('fields')
-    .description('List every <desc> binding in a template by element id, with its source spec and resolved value')
-    .requiredOption('-t, --template <path>', 'path to SVG template')
-    .option('-u, --url <url>', "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(', ') +
-    ' in turn')
-    .option('-e, --example-data <dir>', 'load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u')
+    .command("fields")
+    .description("List every <desc> binding in a template by element id, with its source spec and resolved value")
+    .requiredOption("-t, --template <path>", "path to SVG template")
+    .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
+    DEFAULT_SIGNALK_URLS.join(", ") +
+    " in turn")
+    .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .action(async (opts) => {
-    const doc = new xmldom_1.DOMParser().parseFromString(await (0, promises_1.readFile)(opts.template, 'utf-8'), 'image/svg+xml');
-    const elements = doc.getElementsByTagName('text');
+    const doc = new xmldom_1.DOMParser().parseFromString(await (0, promises_1.readFile)(opts.template, "utf-8"), "image/svg+xml");
     const rows = [];
-    for (let i = 0; i < elements.length; i++) {
-        const element = elements.item(i);
-        const desc = element?.getElementsByTagName('desc').item(0);
-        if (!element || !desc?.textContent)
-            continue;
-        const id = element.getAttribute('id') ?? `#${i}`;
-        try {
-            rows.push({ id, desc: desc.textContent, binding: (0, binding_1.parseBinding)(desc.textContent) });
-        }
-        catch (err) {
-            rows.push({ id, desc: desc.textContent, error: err.message });
+    for (const tag of ["text", "image"]) {
+        const elements = doc.getElementsByTagName(tag);
+        for (let i = 0; i < elements.length; i++) {
+            const element = elements.item(i);
+            const desc = element?.getElementsByTagName("desc").item(0);
+            if (!element || !desc?.textContent)
+                continue;
+            const id = element.getAttribute("id") ?? `${tag}#${i}`;
+            try {
+                rows.push({ id, tag, desc: desc.textContent, binding: (0, binding_1.parseBinding)(desc.textContent) });
+            }
+            catch (err) {
+                rows.push({ id, tag, desc: desc.textContent, error: err.message });
+            }
         }
     }
-    const header = ['id', 'spec', 'value'];
+    const header = ["id", "spec", "value"];
     const table = await Promise.all(rows.map(async (row) => {
         if (row.error || !row.binding)
-            return [row.id, row.desc, row.error ?? ''];
+            return [row.id, row.desc, row.error ?? ""];
         try {
             const context = await assembleContext(opts, [row.binding]);
-            return [row.id, row.desc, (0, binding_1.renderBinding)(row.binding, context)];
+            if (row.tag !== "image") {
+                return [row.id, row.desc, (0, binding_1.renderBinding)(row.binding, context)];
+            }
+            // `<image>` bindings don't substitute text - they pick a `.svg` file (see SvgRenderer) -
+            // so show what asset that resolves to instead of running it through renderBinding's
+            // text formatting, otherwise this row would silently show nothing useful to test against.
+            if (!row.binding.assets) {
+                return [row.id, row.desc, 'ERROR: an <image> binding requires an "assets" key'];
+            }
+            const key = (0, assets_1.normalizeAssetKey)((0, binding_1.resolveBinding)(row.binding, context));
+            if (!key)
+                return [row.id, row.desc, "(no usable value - image would be omitted)"];
+            const assetPath = (0, assets_1.resolveAssetPath)((0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR, row.binding.assets, key);
+            return [
+                row.id,
+                row.desc,
+                assetPath ? `"${key}" -> ${(0, path_1.basename)(assetPath)}` : `"${key}" -> no matching asset file (image would be omitted)`,
+            ];
         }
         catch (err) {
             return [row.id, row.desc, `ERROR: ${err.message}`];
         }
     }));
     const widths = header.map((title, col) => Math.max(title.length, ...table.map((cells) => cells[col].length)));
-    const printRow = (cells) => console.log(cells.map((cell, col) => cell.padEnd(widths[col])).join('  '));
+    const printRow = (cells) => console.log(cells.map((cell, col) => cell.padEnd(widths[col])).join("  "));
     printRow(header);
     table.forEach(printRow);
 });
 program
-    .command('field')
-    .description('Resolve a single binding spec directly against a live SignalK server, with no template')
-    .argument('<spec>', 'binding spec, e.g. "source=resources,resource=tides,path=station.name" or a bare SignalK path')
-    .option('-u, --url <url>', "SignalK server base URL - resolves the spec's source=signalk/resources binding - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(', ') +
-    ' in turn')
-    .option('-e, --example-data <dir>', 'load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u')
+    .command("field")
+    .description("Resolve a single binding spec directly against a live SignalK server, with no template")
+    .argument("<spec>", 'binding spec, e.g. "source=resources,resource=tides,path=station.name" or a bare SignalK path')
+    .option("-u, --url <url>", "SignalK server base URL - resolves the spec's source=signalk/resources binding - if omitted, tries each of " +
+    DEFAULT_SIGNALK_URLS.join(", ") +
+    " in turn")
+    .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .action(async (spec, opts) => {
     const binding = (0, binding_1.parseBinding)(spec);
     const context = await assembleContext(opts, [binding]);

package/dist/cli/liveContext.d.ts

@@ -1,5 +1,5 @@
-import { Binding } from '../render/binding';
-import { TemplateContext } from '../render/types';
+import { Binding } from "../render/binding";
+import { TemplateContext } from "../render/types";
 /**
  * CLI counterpart to `assembleRawContext` + `considerRepaint`'s `meta` injection in
  * repaintScheduler.ts - same `{ signalk, resources, pathMeta, categories, meta }` shape, but fetched

package/dist/cli/liveContext.js

@@ -13,10 +13,10 @@ 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';
+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. */
 function contextPath(context) {
-    return context === 'self' ? 'vessels/self' : context.replace(/\./g, '/');
+    return context === "self" ? "vessels/self" : context.replace(/\./g, "/");
 }
 /**
  * `GET .../vessels/self` (or any other subtree) returns SignalK's full delta-tree shape, where every
@@ -31,12 +31,12 @@ function contextPath(context) {
  * wrapper.
  */
 function unwrapSignalkTree(node) {
-    if (node === null || typeof node !== 'object')
+    if (node === null || typeof node !== "object")
         return node;
     if (Array.isArray(node))
         return node.map(unwrapSignalkTree);
     const obj = node;
-    if ('value' in obj) {
+    if ("value" in obj) {
         return obj.value;
     }
     return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, unwrapSignalkTree(value)]));
@@ -52,7 +52,7 @@ function unwrapSignalkTree(node) {
  */
 async function assembleLiveContext(signalkUrl, bindings) {
     const signalk = {};
-    const contexts = new Set(bindings.filter((binding) => binding.source === 'signalk').map((binding) => binding.context));
+    const contexts = new Set(bindings.filter((binding) => binding.source === "signalk").map((binding) => binding.context));
     for (const context of contexts) {
         const url = `${signalkUrl}/signalk/v1/api/${contextPath(context)}`;
         (0, log_1.logDebug)(`GET ${url}`);
@@ -69,7 +69,7 @@ async function assembleLiveContext(signalkUrl, bindings) {
         }
     }
     const resources = {};
-    const resourceNames = new Set(bindings.filter((binding) => binding.source === 'resources').map((binding) => binding.resource));
+    const resourceNames = new Set(bindings.filter((binding) => binding.source === "resources").map((binding) => binding.resource));
     for (const name of resourceNames) {
         const url = `${signalkUrl}${RESOURCES_API_PATH}/${name}`;
         (0, log_1.logDebug)(`GET ${url}`);
@@ -89,7 +89,7 @@ async function assembleLiveContext(signalkUrl, bindings) {
 async function readJsonFile(filePath) {
     let raw;
     try {
-        raw = await (0, promises_1.readFile)(filePath, 'utf-8');
+        raw = await (0, promises_1.readFile)(filePath, "utf-8");
     }
     catch (err) {
         throw new Error(`could not read example data file ${filePath} - ${err.message}`);
@@ -116,34 +116,34 @@ async function readJsonFile(filePath) {
  */
 async function assembleExampleContext(examplesDir, bindings) {
     const signalk = {};
-    const contexts = new Set(bindings.filter((binding) => binding.source === 'signalk').map((binding) => binding.context));
+    const contexts = new Set(bindings.filter((binding) => binding.source === "signalk").map((binding) => binding.context));
     if (contexts.size > 0) {
-        const vesselsPath = path_1.default.join(examplesDir, 'vessels.json');
+        const vesselsPath = path_1.default.join(examplesDir, "vessels.json");
         (0, log_1.logDebug)(`reading ${vesselsPath}`);
         const vessels = await readJsonFile(vesselsPath);
         for (const context of contexts) {
-            const segments = contextPath(context).split('/');
+            const segments = contextPath(context).split("/");
             let node = vessels;
             for (const segment of segments) {
-                node = node === null || typeof node !== 'object' ? undefined : node[segment];
+                node = node === null || typeof node !== "object" ? undefined : node[segment];
             }
             if (node === undefined) {
-                throw new Error(`example data file ${vesselsPath} has no "${segments.join('.')}" subtree for context "${context}"`);
+                throw new Error(`example data file ${vesselsPath} has no "${segments.join(".")}" subtree for context "${context}"`);
             }
             signalk[context] = unwrapSignalkTree(node);
         }
     }
     const resources = {};
-    const resourceNames = new Set(bindings.filter((binding) => binding.source === 'resources').map((binding) => binding.resource));
+    const resourceNames = new Set(bindings.filter((binding) => binding.source === "resources").map((binding) => binding.resource));
     for (const name of resourceNames) {
-        const resourcePath = path_1.default.join(examplesDir, 'resources', `${name}.json`);
+        const resourcePath = path_1.default.join(examplesDir, "resources", `${name}.json`);
         (0, log_1.logDebug)(`reading ${resourcePath}`);
         resources[name] = await readJsonFile(resourcePath);
     }
     const categoryNames = new Set(bindings.filter((binding) => binding.category).map((binding) => binding.category));
     let categories = {};
     if (categoryNames.size > 0) {
-        const categoriesPath = path_1.default.join(examplesDir, 'categories.json');
+        const categoriesPath = path_1.default.join(examplesDir, "categories.json");
         (0, log_1.logDebug)(`reading ${categoriesPath}`);
         categories = (await readJsonFile(categoriesPath));
         for (const category of categoryNames) {