@rhizomatics/signalk-einklabel-plugin 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,5 @@
+# 0.4.1
+- Packaging fixes
 # 0.4.0
 - Added `einklabel` as a `source` for template fields, and `repainted` as path
 - Added `local_datetime_short` as a datetime format option, for `27 Jun 26 18:05` style output

package/README.md

@@ -1,4 +1,4 @@
-# ESL for SignalK
+# eInk Labels for SignalK
 
 ** BETA - basic functionality, limited vendor/product support **
 

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,12 @@
+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
+ * 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,76 @@
+"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` + `considerRepaint`'s `meta` injection in
+ * repaintScheduler.ts - same `{ signalk, resources, pathMeta, categories, meta }` 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);
+    // 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() };
+    return { signalk, resources, pathMeta, categories, meta };
+}

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;

package/dist/config.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfig = defaultConfig;
+exports.resolveTemplatesDir = resolveTemplatesDir;
+exports.parseDevice = parseDevice;
+exports.resolveTemplatePath = resolveTemplatePath;
+exports.configSchema = configSchema;
+exports.configUiSchema = configUiSchema;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const resolveApiUrl_1 = require("./resolveApiUrl");
+/** The package's own bundled `templates/` directory (ships alongside `dist/`, see package.json's `files`) - templates here are always available, but a same-named template in the user's `templatesDir` takes priority. */
+const BUNDLED_TEMPLATES_DIR = (0, path_1.join)(__dirname, '..', 'templates');
+const SIGNALK_HOME_DIR = (0, path_1.join)((0, os_1.homedir)(), '.signalk');
+const DEFAULT_TEMPLATES_DIR = (0, path_1.join)(SIGNALK_HOME_DIR, 'esl', 'templates');
+function defaultConfig() {
+    return {
+        templatesDir: '',
+        scanOnStart: true,
+        scanDurationSeconds: 20,
+        paintConnectTimeoutSeconds: 30,
+        paintRetries: 3,
+        devices: [],
+    };
+}
+/**
+ * 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.
+ */
+function resolveTemplatesDir(templatesDir) {
+    const trimmed = templatesDir?.trim();
+    if (!trimmed) {
+        return DEFAULT_TEMPLATES_DIR;
+    }
+    return (0, path_1.isAbsolute)(trimmed) ? trimmed : (0, path_1.join)(SIGNALK_HOME_DIR, trimmed);
+}
+/**
+ * Enum for the combined "device" field, built from recently scanned devices - including ones a
+ * driver identified as its vendor but whose PID isn't in its metadata table yet (clearly labelled,
+ * so the user can at least see what was found and report the PID; repainting such a device still
+ * does nothing without a model override, since there's no width/height to render with) - plus, as a
+ * fallback, whatever's already saved so an existing selection doesn't vanish from the dropdown just
+ * because this particular run hasn't re-scanned it yet.
+ */
+function deviceOptions(discovered, current) {
+    const values = [];
+    const labels = [];
+    const seen = new Set();
+    for (const found of discovered) {
+        if (found.pid === undefined) {
+            continue;
+        }
+        const modelToken = [found.vendor, found.pid, found.hwVersion].filter((part) => part !== undefined).join(':');
+        const value = `${modelToken}@${found.address}`;
+        if (seen.has(value)) {
+            continue;
+        }
+        seen.add(value);
+        values.push(value);
+        const label = found.metadata
+            ? `${found.vendor} ${found.metadata.label} (${found.address})`
+            : `${found.vendor} unrecognised PID 0x${found.pid.toString(16).padStart(4, '0')} (${found.address})`;
+        labels.push(label);
+    }
+    for (const device of current.devices) {
+        if (!seen.has(device.device)) {
+            seen.add(device.device);
+            values.push(device.device);
+            labels.push(`${device.device} (not seen in last scan)`);
+        }
+    }
+    return { values, labels };
+}
+function parseDevice(device) {
+    const [modelToken, address] = device.split('@');
+    const [vendor, pidStr, hwVersion] = (modelToken ?? '').split(':');
+    const pid = Number(pidStr);
+    return vendor && address && Number.isInteger(pid) ? { vendor, pid, hwVersion, address } : undefined;
+}
+function listSvgFiles(dir) {
+    try {
+        return (0, fs_1.readdirSync)(dir).filter((name) => name.endsWith('.svg'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Local templates take priority over a same-named bundled one; both show up as options. */
+function templateNameOptions(templatesDir) {
+    const local = listSvgFiles(templatesDir);
+    const bundled = listSvgFiles(BUNDLED_TEMPLATES_DIR).filter((name) => !local.includes(name));
+    return [...local, ...bundled];
+}
+/** Resolves a template name to an actual file path - a local template overrides the bundled one of the same name. */
+function resolveTemplatePath(templatesDir, templateName) {
+    const localPath = (0, path_1.join)(templatesDir, templateName);
+    return (0, fs_1.existsSync)(localPath) ? localPath : (0, path_1.join)(BUNDLED_TEMPLATES_DIR, templateName);
+}
+/** JSON Schema forbids an empty `enum` array, so only attach one when there's at least one option - otherwise the whole config schema fails validation. */
+function withEnum(schema, values, names) {
+    return values.length > 0 ? { ...schema, enum: values, ...(names ? { enumNames: names } : {}) } : schema;
+}
+function configSchema(app, discovered = []) {
+    const defaults = defaultConfig();
+    const current = { ...defaults, ...app.readPluginOptions() };
+    const { values: deviceValues, labels: deviceLabels } = deviceOptions(discovered, current);
+    return {
+        type: 'object',
+        properties: {
+            templatesDir: {
+                type: 'string',
+                title: 'Templates directory',
+                description: `Relative path from ~/.signalk (e.g., "esl/templates" becomes ~/.signalk/esl/templates). ` +
+                    `Leave empty for default (${DEFAULT_TEMPLATES_DIR}). Absolute paths also supported. A template here ` +
+                    'with the same name as a bundled one takes priority.',
+                default: defaults.templatesDir,
+            },
+            scanOnStart: {
+                type: 'boolean',
+                title: 'Scan for devices on plugin start',
+                description: 'Runs a short BLE scan so discovered devices show up in a device\'s "Device" picker below.',
+                default: defaults.scanOnStart,
+            },
+            scanDurationSeconds: {
+                type: 'number',
+                title: 'Scan duration (seconds)',
+                description: 'How long the startup scan runs - increase if devices are missing from the "Device" picker below.',
+                minimum: 1,
+                default: defaults.scanDurationSeconds,
+            },
+            paintConnectTimeoutSeconds: {
+                type: 'number',
+                title: 'Paint connect timeout (seconds)',
+                description: 'How long to wait for a device to accept a BLE connection before giving up on a repaint attempt.',
+                minimum: 1,
+                default: defaults.paintConnectTimeoutSeconds,
+            },
+            paintRetries: {
+                type: 'number',
+                title: 'Paint retries',
+                description: 'How many times to attempt a repaint (including the first try) before giving up and reporting failure.',
+                minimum: 1,
+                default: defaults.paintRetries,
+            },
+            signalkApiUrl: {
+                type: 'string',
+                title: 'SignalK API base URL (leave blank to auto-detect)',
+                description: 'Used for plugin access to SignalK REST APIs not yet integrated for direct plugin access. Left blank, the plugin probes the likely options at startup (3000, 80, 443 ) - only set this manually to skip probing. Anonymous read access is required.',
+                enum: ['', ...resolveApiUrl_1.SIGNALK_API_URL_OPTIONS],
+            },
+            devices: {
+                type: 'array',
+                title: 'Devices',
+                items: {
+                    type: 'object',
+                    required: ['friendlyName', 'device', 'templateName', 'repaintTrigger'],
+                    properties: {
+                        friendlyName: { type: 'string', title: 'Friendly name' },
+                        device: withEnum({
+                            type: 'string',
+                            title: 'Device',
+                            description: 'Picked from devices found by a scan (plugin start, or `esl-cli scan`) - sets both the model and BLE address.',
+                        }, deviceValues, deviceLabels),
+                        templateName: withEnum({ type: 'string', title: 'Template' }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
+                        repaintTrigger: { type: 'string', title: 'Repaint trigger', enum: ['subscription', 'interval'] },
+                        triggerPath: { type: 'string', title: 'Trigger SignalK path (if repaint trigger is subscription)' },
+                        intervalHours: { type: 'number', title: 'Repaint every N hours (if repaint trigger is interval)', minimum: 1 },
+                        intervalMinute: { type: 'number', title: 'Minutes past the hour (if repaint trigger is interval)', minimum: 0, maximum: 59, default: 0 },
+                        aesKey: { type: 'string', title: 'BLE AES key (vendor-specific; leave blank to use a default key)' },
+                        forceRepaint: {
+                            type: 'boolean',
+                            title: 'Force repaint',
+                            description: 'Repaint even if the data is unchanged - clears itself automatically once that repaint completes',
+                            default: false,
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+function configUiSchema() {
+    return {
+        devices: {
+            items: {
+                repaintTrigger: { 'ui:widget': 'radio' },
+            },
+        },
+    };
+}