@rhizomatics/signalk-esl-plugin 0.3.0

package/dist/devices/zhsunyco/index.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZhsunycoDriver = void 0;
+const bleDiscovery_1 = require("../bleDiscovery");
+const metadata_1 = require("./metadata");
+const encode_1 = require("./encode");
+const protocol_1 = require("./protocol");
+/** node-ble has no MTU API; this matches the reference driver's mtu(247)-9 default. */
+const UPLOAD_CHUNK_SIZE = 238;
+const CHUNK_WRITE_DELAY_MS = 20;
+const AUTH_SETTLE_DELAY_MS = 500;
+const STATUS_WAIT_TIMEOUT_MS = 60000;
+const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
+/** Used while identifying a device during a scan - kept short since a scan may be enumerating several devices. */
+const SCAN_CONNECT_TIMEOUT_MS = 10000;
+/** Fallback when `VendorDeviceConfig.connectTimeoutMs` is omitted (e.g. a bare CLI `paint` call) - matches `defaultConfig().paintConnectTimeoutSeconds`. */
+const DEFAULT_PAINT_CONNECT_TIMEOUT_MS = 30000;
+class ZhsunycoDriver {
+    constructor() {
+        this.vendor = 'zhsunyco';
+    }
+    matchesAdvertisement(name, manufacturerId) {
+        return manufacturerId === protocol_1.ZHSUNYCO_MANUFACTURER_ID || (name ?? '').startsWith('WL') || (name ?? '').startsWith('WOESL');
+    }
+    metadataForPid(pid, hwVersion) {
+        const candidates = metadata_1.ZHSUNYCO_PID_METADATA.filter((model) => model.pid === pid);
+        return candidates.find((model) => model.hwVersion === hwVersion) ?? candidates.find((model) => model.hwVersion === undefined);
+    }
+    supportedDevices() {
+        return metadata_1.ZHSUNYCO_PID_METADATA;
+    }
+    async identifyDevice(device, address, name, manufacturerId, manufacturerData) {
+        const advertisedInfo = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
+        const { info, batteryMv } = await readDeviceDetails(device, advertisedInfo);
+        return {
+            address,
+            name,
+            vendor: this.vendor,
+            pid: info?.pid,
+            hwVersion: info?.hwVersion,
+            metadata: info ? this.metadataForPid(info.pid, info.hwVersion) : undefined,
+            manufacturerId,
+            batteryMv,
+            rssi: await device
+                .getRSSI()
+                .then((value) => (value === undefined ? undefined : Number(value)))
+                .catch(() => undefined),
+        };
+    }
+    async paint(bitmap, config) {
+        const aesKey = (0, protocol_1.resolveAesKey)(config.aesKey);
+        const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+        try {
+            const adapter = await bluetooth.defaultAdapter();
+            const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, config.address, DEVICE_DISCOVERY_TIMEOUT_MS);
+            await (0, bleDiscovery_1.connectWithTimeout)(device, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+            try {
+                const gatt = await device.gatt();
+                const service = await gatt.getPrimaryService(protocol_1.WOLINK_SERVICE_UUID);
+                const dataChar = await service.getCharacteristic(protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data);
+                const configChar = await service.getCharacteristic(protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config);
+                const authChar = await service.getCharacteristic(protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate);
+                const statusChar = await service.getCharacteristic(protocol_1.WOLINK_CHARACTERISTIC_UUIDS.status);
+                const info = (0, protocol_1.decodeAdvertisedInfo)(await configChar.readValue());
+                if (!info) {
+                    throw new Error('zhsunyco device did not return valid config data');
+                }
+                const metadata = config.modelOverride
+                    ? { pid: info.pid, ...config.modelOverride }
+                    : this.metadataForPid(info.pid, info.hwVersion);
+                if (!metadata) {
+                    throw new Error(`zhsunyco device reports unrecognised PID 0x${info.pid.toString(16).padStart(4, '0')} - ` +
+                        'pass --width/--height/--voffset/--colours to describe it manually');
+                }
+                const statusReceived = new Promise((resolve, reject) => {
+                    statusChar.once('valuechanged', (data) => {
+                        const { errorCode } = (0, protocol_1.decodeStatus)(data);
+                        if (errorCode === 0) {
+                            resolve();
+                        }
+                        else {
+                            reject(new Error(`zhsunyco device reported error 0x${errorCode.toString(16).padStart(2, '0')} after refresh`));
+                        }
+                    });
+                });
+                await statusChar.startNotifications();
+                const challenge = await authChar.readValue();
+                await authChar.writeValueWithoutResponse((0, protocol_1.authResponse)(challenge, aesKey));
+                await (0, bleDiscovery_1.sleep)(AUTH_SETTLE_DELAY_MS);
+                const pixelData = (0, encode_1.encodeBitmap)(bitmap, metadata);
+                for (let offset = 0; offset < pixelData.length; offset += UPLOAD_CHUNK_SIZE) {
+                    const chunk = pixelData.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
+                    await dataChar.writeValueWithResponse(Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]));
+                    await (0, bleDiscovery_1.sleep)(CHUNK_WRITE_DELAY_MS);
+                }
+                await dataChar.writeValueWithResponse((0, protocol_1.commandHeader)(protocol_1.COMMAND.refreshUncompressed, pixelData.length));
+                await Promise.race([statusReceived, (0, bleDiscovery_1.sleep)(STATUS_WAIT_TIMEOUT_MS)]);
+            }
+            finally {
+                await device.disconnect();
+            }
+        }
+        finally {
+            destroy();
+        }
+    }
+}
+exports.ZhsunycoDriver = ZhsunycoDriver;
+/**
+ * Battery level needs a connection regardless, so reuse it to also fill in the PID/hwVersion
+ * when the advertisement didn't carry decodable manufacturer data - BlueZ's cached
+ * advertisement for a device matched purely by its name prefix can lack that, which would
+ * otherwise leave a real, nearby device's model (and so its entry in the config UI's
+ * device picker - see `deviceOptions()` in `config.ts`) silently missing. Reads the same
+ * config characteristic `paint()` reads, just to identify the device rather than to size a
+ * render.
+ */
+async function readDeviceDetails(device, advertisedInfo) {
+    const fallback = { info: advertisedInfo, batteryMv: undefined };
+    const read = async () => {
+        try {
+            await (0, bleDiscovery_1.connectWithTimeout)(device, SCAN_CONNECT_TIMEOUT_MS);
+            try {
+                const gatt = await device.gatt();
+                const service = await gatt.getPrimaryService(protocol_1.WOLINK_SERVICE_UUID);
+                const batteryChar = await service.getCharacteristic(protocol_1.WOLINK_CHARACTERISTIC_UUIDS.battery);
+                const batteryMv = (0, protocol_1.decodeBatteryMv)(await batteryChar.readValue());
+                let info = advertisedInfo;
+                if (!info) {
+                    const configChar = await service.getCharacteristic(protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config);
+                    info = (0, protocol_1.decodeAdvertisedInfo)(await configChar.readValue());
+                }
+                return { info, batteryMv };
+            }
+            finally {
+                await device.disconnect();
+            }
+        }
+        catch {
+            return fallback;
+        }
+    };
+    // `connectWithTimeout` bounds the connect step itself, but a GATT call past that point (e.g.
+    // `getPrimaryService`/`readValue`) has no timeout of its own either - race the whole read so
+    // one unresponsive device can't stall the rest of the scan (see `plugin.ts`'s `scanInProgress`,
+    // which otherwise stays set forever and silently skips every later scan).
+    return Promise.race([read(), (0, bleDiscovery_1.sleep)(SCAN_CONNECT_TIMEOUT_MS * 2).then(() => fallback)]);
+}

package/dist/devices/zhsunyco/metadata.d.ts

@@ -0,0 +1,20 @@
+import { DeviceMetadata } from '../types';
+/**
+ * Keyed by PID within the Zhsunyco/Wolink namespace only — this table is not shared
+ * with other vendors' PID spaces.
+ *
+ * PID 0x000E is reused across multiple physical panel sizes - the upstream wolink_ble.py
+ * reference driver's own header comment disagrees with its code (`types` dict) about what
+ * 0x000E even is, and OpenEPaperLink's `wolinkToOEPLtype()` independently hit the same
+ * ambiguity. OEPL resolves it via the advertised hwVersion field, listing
+ * 0x0103/0x0201/0x0203 as 2.13"/3.5"/7.5" BWRY panels respectively; the entry below with
+ * no `hwVersion` is the developer's own confirmed 3.7" hardware and is used as the
+ * fallback for any hwVersion not in that list.
+ *
+ * The remaining entries (0x0008/0x000A/0x0012/0x0016/0x001A) are unconfirmed against real
+ * hardware but are taken from wolink_ble.py's `types` dict rather than its header comment,
+ * since none of them shows the kind of hwVersion-dependent reuse 0x000E turned out to
+ * have - there's no reason yet to doubt them the way 0x000E's docstring/code mismatch
+ * gave reason to.
+ */
+export declare const ZHSUNYCO_PID_METADATA: DeviceMetadata[];

package/dist/devices/zhsunyco/metadata.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZHSUNYCO_PID_METADATA = void 0;
+/**
+ * Keyed by PID within the Zhsunyco/Wolink namespace only — this table is not shared
+ * with other vendors' PID spaces.
+ *
+ * PID 0x000E is reused across multiple physical panel sizes - the upstream wolink_ble.py
+ * reference driver's own header comment disagrees with its code (`types` dict) about what
+ * 0x000E even is, and OpenEPaperLink's `wolinkToOEPLtype()` independently hit the same
+ * ambiguity. OEPL resolves it via the advertised hwVersion field, listing
+ * 0x0103/0x0201/0x0203 as 2.13"/3.5"/7.5" BWRY panels respectively; the entry below with
+ * no `hwVersion` is the developer's own confirmed 3.7" hardware and is used as the
+ * fallback for any hwVersion not in that list.
+ *
+ * The remaining entries (0x0008/0x000A/0x0012/0x0016/0x001A) are unconfirmed against real
+ * hardware but are taken from wolink_ble.py's `types` dict rather than its header comment,
+ * since none of them shows the kind of hwVersion-dependent reuse 0x000E turned out to
+ * have - there's no reason yet to doubt them the way 0x000E's docstring/code mismatch
+ * gave reason to.
+ */
+exports.ZHSUNYCO_PID_METADATA = [
+    {
+        pid: 0x0008,
+        label: '1.54"',
+        width: 200,
+        height: 200,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x000a,
+        label: '2.13"',
+        width: 250,
+        height: 128,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x000e,
+        label: '3.7"',
+        width: 416,
+        height: 240,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x000e,
+        hwVersion: '0103',
+        label: '2.13"',
+        width: 250,
+        height: 128,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x000e,
+        hwVersion: '0201',
+        label: '3.5"',
+        width: 384,
+        height: 184,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x000e,
+        hwVersion: '0203',
+        label: '7.5"',
+        width: 800,
+        height: 480,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x0012,
+        label: '2.9"',
+        width: 296,
+        height: 128,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x0016,
+        label: '4.2"',
+        width: 400,
+        height: 300,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+    {
+        pid: 0x001a,
+        label: '5.8"',
+        width: 648,
+        height: 480,
+        voffset: 0,
+        colours: ['black', 'white', 'red', 'yellow'],
+    },
+];

package/dist/devices/zhsunyco/protocol.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Wolink ESL GATT service ("WOLINKBLEESL2020") and characteristic UUIDs, transcribed
+ * from the reference driver (examples/device_driver/zhunyco/wolink_ble.py).
+ */
+export declare const WOLINK_SERVICE_UUID = "30323032-4c53-4545-4c42-4b4e494c4f57";
+/** BLE manufacturer ID Zhsunyco/Wolink devices advertise under. */
+export declare const ZHSUNYCO_MANUFACTURER_ID = 48042;
+export declare const WOLINK_CHARACTERISTIC_UUIDS: {
+    readonly data: "31323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly config: "32323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly authenticate: "33323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly status: "34323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly battery: "35323032-4c53-4545-4c42-4b4e494c4f57";
+};
+export declare const COMMAND: {
+    readonly uploadBlock: 42240;
+    readonly refreshUncompressed: 42241;
+};
+export interface AdvertisedDeviceInfo {
+    pid: number;
+    appVersion: string;
+    hwVersion: string;
+}
+/** Decodes the 8-byte header shared by the advertising mirror and config characteristic. */
+export declare function decodeAdvertisedInfo(data: Buffer): AdvertisedDeviceInfo | undefined;
+export declare function decodeBatteryMv(data: Buffer): number;
+export declare function decodeStatus(data: Buffer): {
+    busy: boolean;
+    errorCode: number;
+};
+/** Builds the 6-byte command header: 2-byte LE command word + 4-byte LE offset/length. */
+export declare function commandHeader(command: number, offsetOrLength?: number): Buffer;
+/**
+ * Stock BLE auth key shared by Wolink ESL devices out of the box (same bytes as the
+ * reference driver's `BLE_SECRET_KEY`). Used as a fallback when a device hasn't been
+ * given its own key via the plugin config.
+ */
+export declare const DEFAULT_BLE_AUTH: number[];
+/** Resolves the configured per-device hex key, falling back to `DEFAULT_BLE_AUTH`. */
+export declare function resolveAesKey(aesKeyHex?: string): Buffer;
+/**
+ * Encrypts the device's auth challenge with the AES-128 key (CBC, zero IV).
+ *
+ * The reference driver PKCS7-pads the challenge before encrypting and keeps only the
+ * first ciphertext block. Since CBC's first output block depends only on the IV and the
+ * plaintext's first block, that's equivalent to encrypting the (already block-sized)
+ * challenge directly with padding disabled — so we skip the pad-then-truncate round trip.
+ */
+export declare function authResponse(challenge: Buffer, key: Buffer): Buffer;

package/dist/devices/zhsunyco/protocol.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BLE_AUTH = exports.COMMAND = exports.WOLINK_CHARACTERISTIC_UUIDS = exports.ZHSUNYCO_MANUFACTURER_ID = exports.WOLINK_SERVICE_UUID = void 0;
+exports.decodeAdvertisedInfo = decodeAdvertisedInfo;
+exports.decodeBatteryMv = decodeBatteryMv;
+exports.decodeStatus = decodeStatus;
+exports.commandHeader = commandHeader;
+exports.resolveAesKey = resolveAesKey;
+exports.authResponse = authResponse;
+const crypto_1 = require("crypto");
+/**
+ * Wolink ESL GATT service ("WOLINKBLEESL2020") and characteristic UUIDs, transcribed
+ * from the reference driver (examples/device_driver/zhunyco/wolink_ble.py).
+ */
+exports.WOLINK_SERVICE_UUID = '30323032-4c53-4545-4c42-4b4e494c4f57';
+/** BLE manufacturer ID Zhsunyco/Wolink devices advertise under. */
+exports.ZHSUNYCO_MANUFACTURER_ID = 0xbbaa;
+exports.WOLINK_CHARACTERISTIC_UUIDS = {
+    data: '31323032-4c53-4545-4c42-4b4e494c4f57',
+    config: '32323032-4c53-4545-4c42-4b4e494c4f57',
+    authenticate: '33323032-4c53-4545-4c42-4b4e494c4f57',
+    status: '34323032-4c53-4545-4c42-4b4e494c4f57',
+    battery: '35323032-4c53-4545-4c42-4b4e494c4f57',
+};
+exports.COMMAND = {
+    uploadBlock: 0xa500,
+    refreshUncompressed: 0xa501,
+};
+/** Decodes the 8-byte header shared by the advertising mirror and config characteristic. */
+function decodeAdvertisedInfo(data) {
+    if (data.length < 8) {
+        return undefined;
+    }
+    return {
+        pid: data.readUInt16BE(2),
+        appVersion: data.readUInt16BE(4).toString(16).padStart(4, '0'),
+        hwVersion: data.readUInt16BE(6).toString(16).padStart(4, '0'),
+    };
+}
+function decodeBatteryMv(data) {
+    return data.readUInt16BE(data.length - 2);
+}
+function decodeStatus(data) {
+    return { busy: data[0] === 0xff, errorCode: data[1] };
+}
+/** Builds the 6-byte command header: 2-byte LE command word + 4-byte LE offset/length. */
+function commandHeader(command, offsetOrLength = 0) {
+    const header = Buffer.alloc(6);
+    header.writeUInt16LE(command, 0);
+    header.writeUInt32LE(offsetOrLength, 2);
+    return header;
+}
+const AES_KEY_LENGTH = 16;
+const AES_CHALLENGE_LENGTH = 16;
+/**
+ * Stock BLE auth key shared by Wolink ESL devices out of the box (same bytes as the
+ * reference driver's `BLE_SECRET_KEY`). Used as a fallback when a device hasn't been
+ * given its own key via the plugin config.
+ */
+exports.DEFAULT_BLE_AUTH = [
+    155, 96, 159, 40, 188, 73, 226, 87,
+    41, 189, 123, 141, 242, 43, 68, 32,
+];
+/** Resolves the configured per-device hex key, falling back to `DEFAULT_BLE_AUTH`. */
+function resolveAesKey(aesKeyHex) {
+    return aesKeyHex ? Buffer.from(aesKeyHex, 'hex') : Buffer.from(exports.DEFAULT_BLE_AUTH);
+}
+/**
+ * Encrypts the device's auth challenge with the AES-128 key (CBC, zero IV).
+ *
+ * The reference driver PKCS7-pads the challenge before encrypting and keeps only the
+ * first ciphertext block. Since CBC's first output block depends only on the IV and the
+ * plaintext's first block, that's equivalent to encrypting the (already block-sized)
+ * challenge directly with padding disabled — so we skip the pad-then-truncate round trip.
+ */
+function authResponse(challenge, key) {
+    if (key.length !== AES_KEY_LENGTH) {
+        throw new Error(`zhsunyco AES key must be ${AES_KEY_LENGTH} bytes (${AES_KEY_LENGTH * 2} hex chars), got ${key.length}`);
+    }
+    if (challenge.length !== AES_CHALLENGE_LENGTH) {
+        throw new Error(`zhsunyco auth challenge expected ${AES_CHALLENGE_LENGTH} bytes, got ${challenge.length}`);
+    }
+    const cipher = (0, crypto_1.createCipheriv)('aes-128-cbc', key, Buffer.alloc(16));
+    cipher.setAutoPadding(false);
+    return Buffer.concat([cipher.update(challenge), cipher.final()]);
+}

package/dist/httpJson.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fetches and parses a JSON endpoint, with an error message that's actually actionable: which URL,
+ * what HTTP status, and the response/underlying error detail - see `describeCause` for why plain
+ * `fetch()` failures need unwrapping to be useful at all.
+ */
+export declare function fetchJson(url: string): Promise<unknown>;

package/dist/httpJson.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchJson = fetchJson;
+/**
+ * Describes a network-level fetch failure's `error.cause` - Node's `fetch()` only ever throws a
+ * generic `TypeError: fetch failed`, with the actually useful detail (e.g. ECONNREFUSED) nested in
+ * `.cause`, and a multi-address connection attempt (e.g. trying both IPv6 and IPv4 for "localhost")
+ * surfaces as an `AggregateError` whose own `.message` is empty - the real detail is in `.errors`.
+ */
+function describeCause(cause) {
+    const errors = cause.errors;
+    if (Array.isArray(errors)) {
+        return errors.map(describeCause).join('; ');
+    }
+    if (cause instanceof Error) {
+        return cause.message || cause.code || cause.toString();
+    }
+    return String(cause);
+}
+/**
+ * Fetches and parses a JSON endpoint, with an error message that's actually actionable: which URL,
+ * what HTTP status, and the response/underlying error detail - see `describeCause` for why plain
+ * `fetch()` failures need unwrapping to be useful at all.
+ */
+async function fetchJson(url) {
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (err) {
+        const cause = err.cause;
+        const detail = cause !== undefined ? describeCause(cause) : err.message;
+        throw new Error(`fetch failed: ${url} - ${detail}`);
+    }
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`fetch failed: ${url} (${response.status} ${response.statusText})${body ? ` - ${body}` : ''}`);
+    }
+    return response.json();
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { ServerAPI, Plugin } from '@signalk/server-api';
+import { registerDriver, getDriver, allDrivers } from './devices/registry';
+import type { VendorDriver as VendorDriverType, DeviceMetadata as DeviceMetadataType, DiscoveredDevice as DiscoveredDeviceType, VendorDeviceConfig as VendorDeviceConfigType, Colour as ColourType } from './devices/types';
+/**
+ * Public extension point for vendor packages. A package that adds support for a new
+ * ESL vendor (e.g. `signalk-esl-shoplabelcorp-plugin`) imports this module and calls
+ * `plugin.registerDriver(new ShopLabelCorpDriver())` from its own SignalK plugin's
+ * `start()` (or at module load time). There's no scanning of installed packages -
+ * registration is always an explicit call by the extension's own code.
+ *
+ * Declare this package as a `peerDependency` (not a regular dependency) in the
+ * extension package, so npm resolves a single shared copy - otherwise the extension
+ * would register into a different registry instance than the one this plugin reads from.
+ */
+declare function plugin(app: ServerAPI): Plugin;
+declare namespace plugin {
+    const registerVendorDriver: typeof registerDriver;
+    const getVendorDriver: typeof getDriver;
+    const allVendorDrivers: typeof allDrivers;
+    type VendorDriver = VendorDriverType;
+    type DeviceMetadata = DeviceMetadataType;
+    type DiscoveredDevice = DiscoveredDeviceType;
+    type VendorDeviceConfig = VendorDeviceConfigType;
+    type Colour = ColourType;
+}
+export = plugin;

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+const plugin_1 = require("./plugin");
+const registry_1 = require("./devices/registry");
+/**
+ * Public extension point for vendor packages. A package that adds support for a new
+ * ESL vendor (e.g. `signalk-esl-shoplabelcorp-plugin`) imports this module and calls
+ * `plugin.registerDriver(new ShopLabelCorpDriver())` from its own SignalK plugin's
+ * `start()` (or at module load time). There's no scanning of installed packages -
+ * registration is always an explicit call by the extension's own code.
+ *
+ * Declare this package as a `peerDependency` (not a regular dependency) in the
+ * extension package, so npm resolves a single shared copy - otherwise the extension
+ * would register into a different registry instance than the one this plugin reads from.
+ */
+function plugin(app) {
+    return (0, plugin_1.createPlugin)(app);
+}
+(function (plugin) {
+    plugin.registerVendorDriver = registry_1.registerDriver;
+    plugin.getVendorDriver = registry_1.getDriver;
+    plugin.allVendorDrivers = registry_1.allDrivers;
+})(plugin || (plugin = {}));
+module.exports = plugin;

package/dist/pathMeta.d.ts

@@ -0,0 +1,16 @@
+import { DisplayUnits } from './render/formatters';
+export interface PathMetadata {
+    units?: string;
+    description?: string;
+    displayUnits?: DisplayUnits;
+}
+/**
+ * Fetches all of a vessel's per-path metadata in one request - `GET .../vessels/<context>/meta` returns
+ * a flat `{ "<dotted.path>": { units, description, displayUnits? }, ... }` map, with `displayUnits`
+ * already fully resolved (category/targetUnit/formula/symbol) server-side. That resolution
+ * (`enhanceMetadataResponse` in signalk-server's `src/interfaces/rest.js`) has no in-process equivalent
+ * reachable via the plugin API (confirmed against the signalk-server source - `app.getMetadata` is
+ * bound directly to the unenhanced `@signalk/path-metadata` package), so both the live plugin
+ * (repaintScheduler.ts) and the CLI (cli/liveContext.ts) fetch it the same way, over HTTP.
+ */
+export declare function fetchPathMeta(apiUrl: string, context: string): Promise<Record<string, PathMetadata>>;

package/dist/pathMeta.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchPathMeta = fetchPathMeta;
+const httpJson_1 = require("./httpJson");
+/** `self` -> `vessels/self`, `vessels.urn:mrn:imo:mmsi:1` -> `vessels/urn:mrn:imo:mmsi:1` - matches the REST path for that context's whole-vessel metadata. */
+function metaContextPath(context) {
+    return context === 'self' ? 'vessels/self' : context.replace(/\./g, '/');
+}
+/**
+ * Fetches all of a vessel's per-path metadata in one request - `GET .../vessels/<context>/meta` returns
+ * a flat `{ "<dotted.path>": { units, description, displayUnits? }, ... }` map, with `displayUnits`
+ * already fully resolved (category/targetUnit/formula/symbol) server-side. That resolution
+ * (`enhanceMetadataResponse` in signalk-server's `src/interfaces/rest.js`) has no in-process equivalent
+ * reachable via the plugin API (confirmed against the signalk-server source - `app.getMetadata` is
+ * bound directly to the unenhanced `@signalk/path-metadata` package), so both the live plugin
+ * (repaintScheduler.ts) and the CLI (cli/liveContext.ts) fetch it the same way, over HTTP.
+ */
+async function fetchPathMeta(apiUrl, context) {
+    const url = `${apiUrl}/signalk/v1/api/${metaContextPath(context)}/meta`;
+    return (await (0, httpJson_1.fetchJson)(url));
+}

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+import { Plugin, ServerAPI } from '@signalk/server-api';
+export declare function createPlugin(app: ServerAPI): Plugin;

package/dist/plugin.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPlugin = createPlugin;
+const config_1 = require("./config");
+const registry_1 = require("./devices/registry");
+const zhsunyco_1 = require("./devices/zhsunyco");
+const bleDiscovery_1 = require("./devices/bleDiscovery");
+const repaintScheduler_1 = require("./repaintScheduler");
+/** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
+async function runStartupScan(app, discovered, durationSeconds) {
+    app.setPluginStatus(`Scanning for ESL devices for ${durationSeconds}s...`);
+    const startedAt = Date.now();
+    let scanError;
+    const drivers = (0, registry_1.allDrivers)();
+    try {
+        await (0, bleDiscovery_1.withDiscovery)(durationSeconds * 1000, async (adapter) => {
+            await (0, bleDiscovery_1.forEachAdvertisedDevice)(adapter, async ({ device, address, name, manufacturerId, manufacturerData }) => {
+                const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
+                if (!driver) {
+                    return;
+                }
+                const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData).catch((err) => {
+                    scanError = `${driver.vendor} scan failed: ${err.message}`;
+                    app.debug(`${scanError}\n${err.stack ?? ''}`);
+                    return undefined;
+                });
+                if (!found) {
+                    return;
+                }
+                discovered.push(found);
+                const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, '0')}` : 'unknown';
+                app.debug(`discovered ${driver.vendor} device "${found.name ?? ''}" [${found.address}] pid=${pid}`);
+            });
+        });
+    }
+    catch (err) {
+        // Without this, an error thrown anywhere in the discovery window (e.g. BlueZ dropping the
+        // D-Bus connection) skips every line below, leaving the admin UI stuck on "Scanning..."
+        // forever even though `discovered` may already hold devices found before the failure.
+        scanError = `scan failed: ${err.message}`;
+        app.debug(`${scanError}\n${err.stack ?? ''}`);
+    }
+    // Surfaces the real cause in the admin UI (instead of only the debug log) - a scan that
+    // ends in well under its configured duration is almost always this, not "no devices nearby".
+    app.setPluginError(scanError ?? '');
+    const elapsedSeconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+    if (discovered.length === 0) {
+        app.setPluginStatus(`Scan complete - no ESL devices found nearby after ${elapsedSeconds} seconds.`);
+        return;
+    }
+    const summary = discovered.map((device) => `${device.name ?? device.vendor} [${device.address}]`).join(', ');
+    app.setPluginStatus(`Scan complete - found ${discovered.length} device(s) in ${elapsedSeconds}s: ${summary} - pick one from a device's "Device" field below`);
+}
+function createPlugin(app) {
+    (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
+    let scheduler;
+    const lastDiscovered = [];
+    // node-ble/BlueZ has no scan-cancellation API, so a scan started by a previous start()
+    // keeps running its full duration even after stop() - tracking it here stops a quick
+    // disable/re-enable from opening a second concurrent D-Bus/BlueZ session, which was
+    // making the new scan fail (and report "no devices found") almost immediately.
+    let scanInProgress;
+    let scanStartedAt;
+    const plugin = {
+        id: 'signalk-esl-plugin',
+        name: 'eInk ESL (Electronic Shelf Label)',
+        description: 'Renders selected SignalK data to BLE eInk Electronic Shelf Labels',
+        schema: () => (0, config_1.configSchema)(app, lastDiscovered),
+        uiSchema: () => (0, config_1.configUiSchema)(),
+        start(config) {
+            const pluginConfig = { ...(0, config_1.defaultConfig)(), ...config };
+            app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
+            if (pluginConfig.scanOnStart) {
+                if (scanInProgress) {
+                    const elapsedSeconds = ((Date.now() - (scanStartedAt ?? Date.now())) / 1000).toFixed(0);
+                    app.debug(`a scan from before this restart is still running (${elapsedSeconds}s) - skipping a new one to avoid a second concurrent BLE session`);
+                    app.setPluginStatus(`Skipped startup scan - a scan from before this restart is still finishing (running ${elapsedSeconds}s) and will update the "Device" picker below once it does.`);
+                }
+                else {
+                    lastDiscovered.length = 0;
+                    scanStartedAt = Date.now();
+                    const scan = runStartupScan(app, lastDiscovered, pluginConfig.scanDurationSeconds).catch((err) => app.debug(`startup scan failed: ${err.message}`));
+                    scanInProgress = scan;
+                    scan.finally(() => {
+                        scanInProgress = undefined;
+                        scanStartedAt = undefined;
+                    });
+                }
+            }
+            scheduler = (0, repaintScheduler_1.startRepaintScheduler)(app, pluginConfig);
+        },
+        stop() {
+            scheduler?.stop();
+            scheduler = undefined;
+            app.debug('stopped');
+        },
+    };
+    return plugin;
+}