@rhizomatics/signalk-einklabel-plugin 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.4.2
+- Fix High/Low display for tide clock template
+- Fix last repaint time for display being hour out
+- Change default name of template directory to 'einklabel/templates'
+# 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 **
 
@@ -30,7 +30,7 @@ In the `description` of the SVG text box, use a comma separated set of key value
 
 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.
 
-#### SignalK REST APIs
+#### SignalK REST APIs
 
 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. 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.
 
@@ -51,6 +51,8 @@ A `format` can be specified to make the value easier to understand. The supporte
 
 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.
 
+Note that for dates and times, the server timezone must be set correctly, for example `Europe/London` rather than the default `Etc/UTC`. This can be done on Linux using `timedatectl` or `raspi-config` if using a Raspberry Pi with Raspian.
+
 Common categories:
 
 * `depth` - Use the SignalK preferred depth unit, make the conversion if needed, and tack on the unit name as a suffix

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;