@rhizomatics/signalk-esl-plugin 0.3.0

package/README.md

@@ -0,0 +1,109 @@
+# ESL for SignalK
+
+** BETA - basic functionality, limited vendor/product support **
+
+A SignalK plugin to display data from SignalK paths, APIs and plugins on Electronic Shelf Labels over a Bluetooth Low Energy (BLE) connection.  
+
+Electronic Shelf Labels (ESLs) are [eInk](https://en.wikipedia.org/wiki/E_Ink) devices that consume very little battery energy, presuming they are not constantly updated - the battery is used only when the display changes, and a periodic BLE check for incoming changes. Perfect for info that changes only once or twice a day, like tidal information.
+
+Since they are designed to be used in large quantity in small shops, they are cheap and simple devices. Earlier models required dedicated controllers, or updates over Wifi or NFC, whereas many modern ones are standalone BLE devices that can be updated from a phone or server.
+
+Unlike some eInk projects, this plugin doesn't require any physical modification to the labels, or loading any new firmware. It can send an image to a supported shelf label fresh out of the box.
+
+## Examples
+
+![Tidal Clock](docs/assets/screenshots/example_tidal_clock.png)
+
+The tide clock needs the [signalk-tides](https://github.com/openwatersio/signalk-tides) plugin to be installed and publishing tides to the Resources API. It can however be customized to run with other APIs or take data only from SignalK data paths.
+
+## Templating
+
+Templates are simply SVG files, to which expressions can be added to use SignalK data, and optionally use helper functions to make it easier to read. The template can have sample data in the placeholder, so is easy to layout and visualize.
+
+### Template Source Specification
+
+In the `description` of the SVG text box, use a comma separated
+set of key value pairs to define the data source and formatting.
+
+For example, `path=environment.forecast.description` uses the default data source (the `self` vessel context) and the named SignalK path. A bare path with no key/value pairs at all, e.g. just `environment.forecast.description`, is shorthand for the same thing. Overriding the default context can be done with `path=environment.forecast.description,context=vessels.urn:mrn:imo:mmsi:232345678` - the `context` value must match a real SignalK context exactly as it appears in the Data Browser; there's nothing to configure for this in the plugin itself.
+
+The source can be overridden to use the SignalK server's Resources API instead. For example, `source=resources,resource=tides,path=station.name` picks the `tides` resource and pulls the `station.name` path out of the JSON response - this works for any resource type (`tides`, `waypoints`, `routes`, ...), and needs nothing configured: the plugin reaches the Resources API directly (`app.resourcesApi`), not over HTTP. Where a resource is specified, it will be fetched once for that render, and subsequent fields sourced from the same resource use that cached response.
+
+A `format` can be specified to make the value easier to understand. The supported formats are:
+
+* `local_time` - reduce a time stamp to just the time, omitting the date, and applying daylight savings if appropriate
+* `day_mon` - reduce a time stamp to day and month, e.g. `27 Jun`, applying daylight savings if appropriate
+* `utc_offset` - Show a timezone in `UTC+01:00` style format
+* `position` - Format a `{ latitude, longitude }` value as decimal degrees with hemisphere letters, e.g. `56.6250°N 6.0700°W`
+* `raw` - Don't apply automatic SignalK unit conversion and symbol display (see below)
+
+SignalK's unit preferences are used to automatically convert a `signalk`-sourced numeric value to its preferred display unit, and append a unit symbol like `kt` or `m`, unless `format=raw` is specified to switch that off. However, when using plugin or API data there may be no path metadata to convert from (for example `signalk-tides` publishes tide data to the Resources API, and `level` is a raw metre value with no SignalK path of its own) - in these cases an explicit `category` can be given instead, and the unit preferences will be applied the same way, for example `category=depth` for the tides level figure.
+
+Common categories:
+
+* `depth` - Use the SignalK preferred depth unit, make the conversion if needed, and tack on the unit name as a suffix
+* `speed` - Use the SignalK preferred speed unit, make the conversion if needed, and tack on the unit name as a suffix
+* `temperature` - Use the SignalK preferred temperature unit, make the conversion if needed, and tack on the unit name as a suffix
+
+Additionally, `round=n` can be used to round to limited decimal places.
+
+These can all be combined as in `source=resources,resource=tides,path=extremes[2].level,category=depth,round=2`
+
+## CLI
+
+To get fast feedback on templates and shelf devices without updating and configuring SignalK, a CLI is provided that has these commands.
+
+- `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
+
+## Vendors
+
+### Zhsunyco
+
+Also known as 'Suny'
+
+- [BLE ESLs](https://www.zhsunyco.com/digital-display-solution-for-small-retail-business/ble-esl-solution/)
+  - The range of labels available on retail sites like AliExpress may be larger than on their corporate site
+  - In mid 2026, a 4 colour (BWRY) 3.7" label retailed for about $35, with quantity discounts for bulk sets
+  - Cheapest units are 2 colour 1.54", and they go up to 7.5"
+
+Python code for a variety of their labels at https://github.com/roxburghm/zhsunyco-esl and https://github.com/NickWaterton/Wolink
+
+## Architecture
+
+The primary things managed and provided by the plugin are:
+
+* ESL Vendor
+* ESL Device
+* SVG Template
+* SignalK API base URL
+  - Used for automatic unit conversion on `signalk`-sourced numeric values and for resolving an explicit `category=` binding - neither has an in-process equivalent, both go via this server's own REST API
+  - Optional: left blank, the plugin probes the only realistic values in likelihood order at startup - `http://localhost:3000` (bare npm install), `http://localhost`, `https://localhost` (container/systemd installs) - and uses whichever responds, since it always runs on the same host as the server. 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
+
+### Extending
+
+#### Hardware
+
+Additional vendors and devices can be added by a separate npm package that implements the `VendorDriver` interface and registers itself - there's no scanning of installed packages, registration is always an explicit call by the extension's own code.
+
+- `import esl from '@rhizomatics/signalk-esl-plugin'; esl.registerVendorDriver(myDriver)`
+- In the SignalK runtime, call this from the extension's own plugin `start()`. In the CLI, load the extension with `esl-cli --require <module> <command>`.
+- Declare this package as a `peerDependency` (not a regular dependency) in the extension package, so npm resolves a single shared copy of the registry.
+
+#### Developing Templates
+
+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).
+
+Inkscape adds its own metadata to images, which can be stripped off by exporting a simple SVG, although can be left in place with no harm; main reason to simplify the SVG is manual changes in a text editor.
+
+The `esl-cli` can be used to debug and validate templates quickly:
+
+* `render` - Render templates with SignalK data and write to a local PNG file
+* `paint` - Render templates with SignalK data and send to selected ESL device
+* `fields` - List the fields in the template, with the source specification and the rendered data value
+* `field` - Accept a source specification (outside of any template context) and return the rendered value if available

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("fs/promises");
+const commander_1 = require("commander");
+const xmldom_1 = require("@xmldom/xmldom");
+const registry_1 = require("../devices/registry");
+const zhsunyco_1 = require("../devices/zhsunyco");
+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 liveContext_1 = require("./liveContext");
+const log_1 = require("./log");
+(0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
+const VENDOR_IDENTIFY_TIMEOUT_MS = 30000;
+const DEFAULT_SIGNALK_URL = 'http://localhost:3000';
+const COLOUR_CODES = {
+    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(', ')}`);
+    }
+    return colours;
+}
+/** Connects long enough to read the advertised name and manufacturer ID, then matches against registered drivers. */
+async function identifyVendor(address) {
+    const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+    try {
+        (0, log_1.logDebug)(`connecting to ${address} to identify its vendor (timeout ${VENDOR_IDENTIFY_TIMEOUT_MS}ms)`);
+        const adapter = await bluetooth.defaultAdapter();
+        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'}`);
+        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`);
+        }
+        return driver.vendor;
+    }
+    finally {
+        destroy();
+    }
+}
+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', () => {
+    (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')
+    .action(() => {
+    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}` : '',
+                device.label,
+                `${device.width}x${device.height}`,
+                device.colours.join(','),
+            ]);
+        }
+    }
+    if (rows.length === 0) {
+        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('  '));
+    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')
+    .action(async (opts) => {
+    const durationMs = Number(opts.duration) * 1000;
+    const header = ['vendor', 'address', 'name', 'pid', 'label', 'mfr', 'battery', 'rssi'];
+    const rows = [];
+    let matchedCount = 0;
+    const drivers = (0, registry_1.allDrivers)();
+    (0, log_1.logDebug)(`scanning for ${durationMs}ms`);
+    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')}` : '';
+            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 ?? '')]);
+                }
+                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 ?? '')]);
+        });
+    });
+    if (matchedCount === 0) {
+        console.log(`no devices found in ${opts.duration}s - try a longer scan with -d, e.g. "-d 30"`);
+    }
+    if (rows.length === 0) {
+        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('  '));
+    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', DEFAULT_SIGNALK_URL)
+    .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);
+    if (!driver) {
+        throw new Error(`no driver registered for vendor "${vendor}"`);
+    }
+    const modelOverride = opts.colours
+        ? {
+            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 context = await (0, liveContext_1.assembleLiveContext)(opts.url, bindings);
+    const renderer = new svgRenderer_1.SvgRenderer();
+    const bitmap = await renderer.render(opts.template, context, Number(opts.width), Number(opts.height));
+    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}`);
+        }
+        await driver.paint(bitmap, { address: opts.address, aesKey: opts.aesKey, modelOverride, connectTimeoutMs });
+    });
+    console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height})`);
+});
+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', DEFAULT_SIGNALK_URL)
+    .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])
+    .action(async (opts) => {
+    const bindings = (0, binding_1.findBindings)(await (0, promises_1.readFile)(opts.template, 'utf-8'));
+    const context = await (0, liveContext_1.assembleLiveContext)(opts.url, 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));
+    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', DEFAULT_SIGNALK_URL)
+    .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 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 });
+        }
+    }
+    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 ?? ''];
+        try {
+            const context = await (0, liveContext_1.assembleLiveContext)(opts.url, [row.binding]);
+            return [row.id, row.desc, (0, binding_1.renderBinding)(row.binding, context)];
+        }
+        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('  '));
+    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', DEFAULT_SIGNALK_URL)
+    .action(async (spec, opts) => {
+    const binding = (0, binding_1.parseBinding)(spec);
+    const context = await (0, liveContext_1.assembleLiveContext)(opts.url, [binding]);
+    console.log((0, binding_1.renderBinding)(binding, context));
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err.message);
+    process.exitCode = 1;
+});

package/dist/cli/liveContext.d.ts

@@ -0,0 +1,11 @@
+import { Binding } from '../render/binding';
+import { TemplateContext } from '../render/types';
+/**
+ * CLI counterpart to `assembleRawContext` in repaintScheduler.ts - same `{ signalk, resources,
+ * pathMeta, categories }` shape, but fetched entirely over plain HTTP (the CLI has no live `ServerAPI`
+ * to call `getSelfPath`/`getPath`/`resourcesApi` on, and per-path metadata/`category=` resolution has
+ * no in-process equivalent at all - see `repaintScheduler.ts`) against a real or test SignalK server's
+ * REST API. Fetches each referenced context's/resource's *whole* subtree once and lets the existing
+ * binding resolver navigate `path` within it.
+ */
+export declare function assembleLiveContext(signalkUrl: string, bindings: Binding[]): Promise<TemplateContext>;

package/dist/cli/liveContext.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleLiveContext = assembleLiveContext;
+const httpJson_1 = require("../httpJson");
+const unitCategories_1 = require("../unitCategories");
+const pathMeta_1 = require("../pathMeta");
+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. */
+function contextPath(context) {
+    return context === 'self' ? 'vessels/self' : context.replace(/\./g, '/');
+}
+/**
+ * `GET .../vessels/self` (or any other subtree) returns SignalK's full delta-tree shape, where every
+ * leaf is wrapped as `{ value, $source, timestamp, ... }` rather than the bare value - unlike
+ * `app.getSelfPath`/`getPath` in the live plugin (repaintScheduler.ts), which already return bare
+ * values. Recursively unwraps every such leaf so `path=` bindings resolve the same way over HTTP as
+ * they do live. Only applied to `signalk` fetches - `resources` responses have no such wrapper.
+ *
+ * Keys off `value` alone, not also requiring `timestamp`/`$source` - not every server includes both on
+ * every leaf, and a `value` key is otherwise meaningless on a SignalK data-model node (it isn't a
+ * regular vessel property name), so there's no real risk of unwrapping something that isn't this
+ * wrapper.
+ */
+function unwrapSignalkTree(node) {
+    if (node === null || typeof node !== 'object')
+        return node;
+    if (Array.isArray(node))
+        return node.map(unwrapSignalkTree);
+    const obj = node;
+    if ('value' in obj) {
+        return obj.value;
+    }
+    return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, unwrapSignalkTree(value)]));
+}
+/**
+ * CLI counterpart to `assembleRawContext` in repaintScheduler.ts - same `{ signalk, resources,
+ * pathMeta, categories }` shape, but fetched entirely over plain HTTP (the CLI has no live `ServerAPI`
+ * to call `getSelfPath`/`getPath`/`resourcesApi` on, and per-path metadata/`category=` resolution has
+ * no in-process equivalent at all - see `repaintScheduler.ts`) against a real or test SignalK server's
+ * REST API. Fetches each referenced context's/resource's *whole* subtree once and lets the existing
+ * binding resolver navigate `path` within it.
+ */
+async function assembleLiveContext(signalkUrl, bindings) {
+    const signalk = {};
+    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}`);
+        signalk[context] = unwrapSignalkTree(await (0, httpJson_1.fetchJson)(url));
+    }
+    const pathMeta = {};
+    for (const context of contexts) {
+        try {
+            (0, log_1.logDebug)(`GET ${signalkUrl}/signalk/v1/api/${contextPath(context)}/meta`);
+            pathMeta[context] = await (0, pathMeta_1.fetchPathMeta)(signalkUrl, context);
+        }
+        catch (err) {
+            console.error(`warning: could not fetch path metadata for context "${context}" (${err.message}) - automatic unit conversion will show raw values`);
+        }
+    }
+    const resources = {};
+    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}`);
+        resources[name] = await (0, httpJson_1.fetchJson)(url);
+    }
+    const categoryNames = new Set(bindings.filter((binding) => binding.category).map((binding) => binding.category));
+    const categories = await (0, unitCategories_1.fetchCategoryDisplayUnits)(signalkUrl, categoryNames);
+    return { signalk, resources, pathMeta, categories };
+}

package/dist/cli/log.d.ts

@@ -0,0 +1,5 @@
+export type LogLevel = 'info' | 'debug';
+/** Set once from the global `--log-level` option (see index.ts's `preAction` hook) - applies to every command. */
+export declare function setLogLevel(level: string): void;
+/** Internal tracing (e.g. which URL is being fetched) - silent unless --log-level debug, so default output stays uncluttered. */
+export declare function logDebug(message: string): void;

package/dist/cli/log.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLogLevel = setLogLevel;
+exports.logDebug = logDebug;
+const LEVELS = ['info', 'debug'];
+let currentLevel = 'info';
+/** Set once from the global `--log-level` option (see index.ts's `preAction` hook) - applies to every command. */
+function setLogLevel(level) {
+    if (!LEVELS.includes(level)) {
+        throw new Error(`unknown --log-level "${level}" - expected one of ${LEVELS.join(', ')}`);
+    }
+    currentLevel = level;
+}
+/** Internal tracing (e.g. which URL is being fetched) - silent unless --log-level debug, so default output stays uncluttered. */
+function logDebug(message) {
+    if (currentLevel === 'debug')
+        console.error(`[debug] ${message}`);
+}

package/dist/config.d.ts

@@ -0,0 +1,74 @@
+import { ServerAPI } from '@signalk/server-api';
+import { DiscoveredDevice } from './devices/types';
+export interface DeviceConfig {
+    friendlyName: string;
+    /**
+     * `"<vendor>:<pid>[:<hwVersion>]@<address>"`, picked from a combined enum of recently
+     * scanned devices so one selection sets both the model (width/height/colours, known
+     * without a live BLE read) and the BLE address.
+     */
+    device: string;
+    /** Per-device override; if omitted, the vendor driver may fall back to a stock/manufacturer-default key. */
+    aesKey?: string;
+    templateName: string;
+    repaintTrigger: 'subscription' | 'interval';
+    /** SignalK path to subscribe to when `repaintTrigger` is `subscription` - a repaint is considered on every delta. */
+    triggerPath?: string;
+    /** When `repaintTrigger` is `interval`: repaint every N hours... */
+    intervalHours?: number;
+    /** ...at this minute past the hour. */
+    intervalMinute?: number;
+    /** One-shot override to repaint even if the data is unchanged; cleared automatically once that repaint completes. */
+    forceRepaint?: boolean;
+}
+export interface PluginConfig {
+    /**
+     * Directory the plugin scans for template files, instead of an upload UI - follows
+     * signalk-parquet's convention: empty for the default, a relative path resolved against
+     * `~/.signalk`, or an absolute path. Use `resolveTemplatesDir` to turn this into an actual path.
+     */
+    templatesDir: string;
+    /** Run a short BLE scan on plugin start and report discoveries via plugin status, like signalk-bluetti-plugin does. */
+    scanOnStart: boolean;
+    /** How long the startup scan runs, in seconds. */
+    scanDurationSeconds: number;
+    /** How long to wait for a device to accept a BLE connection before giving up on a repaint attempt, in seconds. */
+    paintConnectTimeoutSeconds: number;
+    /** How many times to attempt a repaint (including the first try) before giving up and reporting failure. */
+    paintRetries: 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
+     * explicit `category=` binding (e.g. `category=depth` on a resource-sourced value with no path
+     * metadata of its own, see `../unitCategories.ts`). Neither has an in-process equivalent reachable via
+     * the plugin API - confirmed against the signalk-server source, this resolution only happens in its
+     * REST layer.
+     *
+     * Always the local loopback address - the plugin runs on the same host as the server, so it's
+     * reachable regardless of any external reverse proxy. Left unset, the plugin probes
+     * `SIGNALK_API_URL_OPTIONS` at startup (in likelihood order: 3000 for a bare `npm install`, then
+     * 80/443 for container/systemd installs) and uses whichever responds - see `./resolveApiUrl.ts`. Set
+     * explicitly only to skip probing or to confirm a specific one is reachable; either way, it must allow
+     * anonymous read access - the plugin has no login flow.
+     */
+    signalkApiUrl?: string;
+    devices: DeviceConfig[];
+}
+export declare function defaultConfig(): PluginConfig;
+/**
+ * Resolves the user-facing `templatesDir` setting to an actual directory, mirroring
+ * signalk-parquet's `outputDirectory` convention: empty means the default location, a relative
+ * path is resolved against `~/.signalk` (where SignalK itself stores its config by default), and
+ * an absolute path is used as-is.
+ */
+export declare function resolveTemplatesDir(templatesDir: string | undefined): string;
+export declare function parseDevice(device: string): {
+    vendor: string;
+    pid: number;
+    hwVersion?: string;
+    address: string;
+} | undefined;
+/** Resolves a template name to an actual file path - a local template overrides the bundled one of the same name. */
+export declare function resolveTemplatePath(templatesDir: string, templateName: string): string;
+export declare function configSchema(app: ServerAPI, discovered?: DiscoveredDevice[]): object;
+export declare function configUiSchema(): object;