@rhizomatics/signalk-einklabel-plugin 0.4.0 → 0.4.1

package/dist/devices/bleDiscovery.d.ts

@@ -0,0 +1,54 @@
+import { Adapter, Bluetooth, Device } from 'node-ble';
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Drop-in replacement for `node-ble`'s `createBluetooth` that fails fast and clearly when
+ * BLE isn't available at all, instead of letting `dbus-next` crash the whole process.
+ *
+ * `node-ble` connects to BlueZ over D-Bus, which only exists on Linux. On any other
+ * platform (e.g. a developer's Mac), the underlying `dbus-next` socket connection fails
+ * and emits an `'error'` event with no listener attached - Node treats that as an
+ * uncaught exception rather than a promise rejection, so no `try`/`catch` around
+ * `createBluetooth()` or its callers can see it; it takes the whole process down.
+ */
+export declare function createBluetooth(): {
+    bluetooth: Bluetooth;
+    destroy: () => void;
+};
+/** BLE manufacturer ID advertised by the device, if any - the key of its manufacturer data map. */
+export declare function getManufacturerId(device: Device): Promise<number | undefined>;
+export interface AdvertisedDevice {
+    address: string;
+    device: Device;
+    name?: string;
+    manufacturerId?: number;
+    manufacturerData?: Buffer;
+}
+/**
+ * Reads each nearby device's advertisement exactly once and hands it to `fn` - shared by
+ * `plugin.ts`'s startup scan and the CLI's `scan` command so that identifying which vendor (if
+ * any) a device belongs to costs one `getName`/`getManufacturerData` read per device total, not
+ * one per device per registered driver.
+ */
+export declare function forEachAdvertisedDevice(adapter: Adapter, fn: (advertised: AdvertisedDevice) => Promise<void>): Promise<void>;
+/**
+ * Retries `fn` up to `attempts` times (including the first try), returning on the first success -
+ * shared by the repaint scheduler and the CLI's `paint` command so one flaky BLE connection
+ * doesn't fail a whole repaint after a single bad attempt.
+ */
+export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>): Promise<T>;
+/**
+ * Opens exactly one BLE discovery window and one D-Bus/BlueZ session, then hands the adapter to
+ * `fn` - shared by `plugin.ts`'s startup scan and the CLI's `scan` command so scanning across
+ * multiple registered vendor drivers costs one discovery window total, not one window per driver.
+ */
+export declare function withDiscovery<T>(durationMs: number, fn: (adapter: Adapter) => Promise<T>): Promise<T>;
+/**
+ * `device.connect()` has no timeout of its own - BlueZ's underlying D-Bus `Connect` call can hang
+ * indefinitely for a device that's out of range or stuck mid-handshake, which would otherwise
+ * block a scan (or `paint()`) on that one device forever. Throws once `timeoutMs` elapses; if the
+ * connect does eventually resolve afterwards, disconnects in the background so a stray successful
+ * connection doesn't itself block the next attempt.
+ */
+export declare function connectWithTimeout(device: Device, timeoutMs: number): Promise<void>;
+/** Uses an already-known device if BlueZ has one cached, otherwise scans until it appears. */
+export declare function getOrDiscoverDevice(adapter: Adapter, address: string, timeoutMs: number): Promise<Device>;

package/dist/devices/bleDiscovery.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = sleep;
+exports.createBluetooth = createBluetooth;
+exports.getManufacturerId = getManufacturerId;
+exports.forEachAdvertisedDevice = forEachAdvertisedDevice;
+exports.withRetries = withRetries;
+exports.withDiscovery = withDiscovery;
+exports.connectWithTimeout = connectWithTimeout;
+exports.getOrDiscoverDevice = getOrDiscoverDevice;
+const node_ble_1 = require("node-ble");
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Drop-in replacement for `node-ble`'s `createBluetooth` that fails fast and clearly when
+ * BLE isn't available at all, instead of letting `dbus-next` crash the whole process.
+ *
+ * `node-ble` connects to BlueZ over D-Bus, which only exists on Linux. On any other
+ * platform (e.g. a developer's Mac), the underlying `dbus-next` socket connection fails
+ * and emits an `'error'` event with no listener attached - Node treats that as an
+ * uncaught exception rather than a promise rejection, so no `try`/`catch` around
+ * `createBluetooth()` or its callers can see it; it takes the whole process down.
+ */
+function createBluetooth() {
+    if (process.platform !== 'linux') {
+        throw new Error(`BLE support requires Linux (BlueZ over D-Bus); "${process.platform}" is not supported - ` +
+            'run this on the target Linux host (e.g. the NanoPi), not on macOS/Windows.');
+    }
+    return (0, node_ble_1.createBluetooth)();
+}
+/** BLE manufacturer ID advertised by the device, if any - the key of its manufacturer data map. */
+async function getManufacturerId(device) {
+    const manufacturerData = await device.getManufacturerData().catch(() => undefined);
+    const [key] = Object.keys(manufacturerData ?? {});
+    return key === undefined ? undefined : Number(key);
+}
+/**
+ * Reads each nearby device's advertisement exactly once and hands it to `fn` - shared by
+ * `plugin.ts`'s startup scan and the CLI's `scan` command so that identifying which vendor (if
+ * any) a device belongs to costs one `getName`/`getManufacturerData` read per device total, not
+ * one per device per registered driver.
+ */
+async function forEachAdvertisedDevice(adapter, fn) {
+    for (const address of await adapter.devices()) {
+        // BlueZ can drop a device from its cache between `adapter.devices()` listing it and this
+        // lookup (e.g. it went out of range mid-scan) - skip it rather than aborting the whole scan.
+        const device = await adapter.getDevice(address).catch(() => undefined);
+        if (!device) {
+            continue;
+        }
+        const name = await device.getName().catch(() => undefined);
+        const manufacturerData = await device.getManufacturerData().catch(() => undefined);
+        const [key] = Object.keys(manufacturerData ?? {});
+        const manufacturerId = key === undefined ? undefined : Number(key);
+        await fn({ address, device, name, manufacturerId, manufacturerData: key === undefined ? undefined : manufacturerData[key] });
+    }
+}
+/**
+ * Retries `fn` up to `attempts` times (including the first try), returning on the first success -
+ * shared by the repaint scheduler and the CLI's `paint` command so one flaky BLE connection
+ * doesn't fail a whole repaint after a single bad attempt.
+ */
+async function withRetries(attempts, fn) {
+    let lastErr;
+    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}
+/**
+ * Opens exactly one BLE discovery window and one D-Bus/BlueZ session, then hands the adapter to
+ * `fn` - shared by `plugin.ts`'s startup scan and the CLI's `scan` command so scanning across
+ * multiple registered vendor drivers costs one discovery window total, not one window per driver.
+ */
+async function withDiscovery(durationMs, fn) {
+    const { bluetooth, destroy } = createBluetooth();
+    try {
+        const adapter = await bluetooth.defaultAdapter();
+        const wasDiscovering = await adapter.isDiscovering();
+        if (!wasDiscovering) {
+            await adapter.startDiscovery();
+        }
+        await sleep(durationMs);
+        if (!wasDiscovering) {
+            await adapter.stopDiscovery();
+        }
+        return await fn(adapter);
+    }
+    finally {
+        destroy();
+    }
+}
+/**
+ * `device.connect()` has no timeout of its own - BlueZ's underlying D-Bus `Connect` call can hang
+ * indefinitely for a device that's out of range or stuck mid-handshake, which would otherwise
+ * block a scan (or `paint()`) on that one device forever. Throws once `timeoutMs` elapses; if the
+ * connect does eventually resolve afterwards, disconnects in the background so a stray successful
+ * connection doesn't itself block the next attempt.
+ */
+async function connectWithTimeout(device, timeoutMs) {
+    const connecting = device.connect();
+    let timedOut = false;
+    await Promise.race([connecting, sleep(timeoutMs).then(() => void (timedOut = true))]);
+    if (timedOut) {
+        connecting.then(() => device.disconnect()).catch(() => { });
+        throw new Error(`connecting to device timed out after ${timeoutMs}ms`);
+    }
+}
+/** Uses an already-known device if BlueZ has one cached, otherwise scans until it appears. */
+async function getOrDiscoverDevice(adapter, address, timeoutMs) {
+    try {
+        return await adapter.getDevice(address);
+    }
+    catch {
+        const wasDiscovering = await adapter.isDiscovering();
+        if (!wasDiscovering) {
+            await adapter.startDiscovery();
+        }
+        try {
+            return await adapter.waitDevice(address, timeoutMs);
+        }
+        finally {
+            if (!wasDiscovering) {
+                await adapter.stopDiscovery();
+            }
+        }
+    }
+}

package/dist/devices/registry.d.ts

@@ -0,0 +1,4 @@
+import { VendorDriver } from './types';
+export declare function registerDriver(driver: VendorDriver): void;
+export declare function getDriver(vendor: string): VendorDriver | undefined;
+export declare function allDrivers(): VendorDriver[];

package/dist/devices/registry.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDriver = registerDriver;
+exports.getDriver = getDriver;
+exports.allDrivers = allDrivers;
+const drivers = new Map();
+function registerDriver(driver) {
+    drivers.set(driver.vendor, driver);
+}
+function getDriver(vendor) {
+    return drivers.get(vendor);
+}
+function allDrivers() {
+    return [...drivers.values()];
+}

package/dist/devices/types.d.ts

@@ -0,0 +1,70 @@
+import { Device } from 'node-ble';
+import { Bitmap } from '../render/types';
+export type Colour = 'black' | 'white' | 'red' | 'yellow';
+/**
+ * Static facts about one device model, keyed by (vendor, pid) by the registry —
+ * PID alone is not assumed unique across vendors.
+ */
+export interface DeviceMetadata {
+    pid: number;
+    /**
+     * Disambiguates physical hardware that shares a PID (some vendors reuse PIDs across
+     * panel sizes) - the exact advertised value to match against; omit for the variant
+     * that should be treated as the default/fallback for that PID.
+     */
+    hwVersion?: string;
+    label: string;
+    width: number;
+    height: number;
+    voffset: number;
+    colours: Colour[];
+}
+export interface DiscoveredDevice {
+    address: string;
+    name?: string;
+    vendor: string;
+    pid?: number;
+    /**
+     * The advertised hardware-version disambiguator, captured independently of whether `metadata`
+     * lookup succeeded - lets `deviceOptions()` (`config.ts`) build a complete, parseable device token
+     * even for a PID a driver doesn't recognise yet, instead of losing it because it was only ever
+     * read off of `metadata.hwVersion`.
+     */
+    hwVersion?: string;
+    metadata?: DeviceMetadata;
+    rssi?: number;
+    /** BLE manufacturer ID (the key of the advertisement's manufacturer data), if advertised. */
+    manufacturerId?: number;
+    /** Battery level in millivolts, if the driver was able to read it during the scan. */
+    batteryMv?: number;
+}
+/** Manual model facts a user can supply for hardware that isn't yet in a driver's PID table. */
+export type DeviceModelOverride = Omit<DeviceMetadata, 'pid'>;
+/** Per-device settings the user supplies when registering a device, beyond what's in DeviceMetadata. */
+export interface VendorDeviceConfig {
+    address: string;
+    /** AES key for vendors that need it, entered by the user. If omitted, vendors that have one may fall back to a stock/manufacturer-default key instead of failing. */
+    aesKey?: string;
+    /** Forces the device model facts instead of looking up the advertised PID - for hardware not yet in the driver's table. */
+    modelOverride?: DeviceModelOverride;
+    /** How long to wait for the BLE connect step before giving up - if omitted, the driver picks its own default. */
+    connectTimeoutMs?: number;
+}
+export interface VendorDriver {
+    vendor: string;
+    /** Does this advertisement look like it came from one of this vendor's devices? */
+    matchesAdvertisement(name: string | undefined, manufacturerId: number | undefined): boolean;
+    /** hwVersion disambiguates PIDs a vendor reuses across panel sizes - see `DeviceMetadata.hwVersion`. */
+    metadataForPid(pid: number, hwVersion?: string): DeviceMetadata | undefined;
+    /** All device models this driver currently has confirmed metadata for. */
+    supportedDevices(): DeviceMetadata[];
+    /**
+     * Identifies one device the shared caller (see `bleDiscovery.ts`'s `forEachAdvertisedDevice`)
+     * has already matched to this vendor via `matchesAdvertisement` - only called for matches, so a
+     * device gets at most one vendor-specific connect/read regardless of how many drivers are
+     * registered, not one attempt per driver.
+     */
+    identifyDevice(device: Device, address: string, name: string | undefined, manufacturerId: number | undefined, manufacturerData: Buffer | undefined): Promise<DiscoveredDevice>;
+    /** Quantise the common bitmap to this device's palette/encoding and send it over BLE. */
+    paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
+}

package/dist/devices/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,12 @@
+import { Bitmap } from '../../render/types';
+import { DeviceMetadata } from '../types';
+/**
+ * Quantises a common RGBA bitmap and packs it into the Wolink wire format: 2 bits per
+ * pixel, 4 pixels per byte, column-major, with both axes flipped (RAM is x/y-flipped
+ * relative to the displayed image). Mirrors `make_image`/`from_pillow` in the reference
+ * driver (examples/device_driver/zhunyco/wolink_ble.py).
+ *
+ * Rows above `voffset` (present on some panel sizes) are sent as black, matching the
+ * reference driver pasting the source image at a vertical offset onto a blank canvas.
+ */
+export declare function encodeBitmap(bitmap: Bitmap, metadata: DeviceMetadata): Buffer;

package/dist/devices/zhsunyco/encode.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeBitmap = encodeBitmap;
+/** Mirrors the reference driver's `from_pillow` nearest-colour decision tree. */
+function nearestColour(r, g, b) {
+    if (r > 150 && g > 150 && b > 150)
+        return 1 /* WolinkColour.White */;
+    if (r > 150 && g > 100 && b < 80)
+        return 2 /* WolinkColour.Yellow */;
+    if (r > 150 && g < 80 && b < 80)
+        return 3 /* WolinkColour.Red */;
+    return 0 /* WolinkColour.Black */;
+}
+/**
+ * Quantises a common RGBA bitmap and packs it into the Wolink wire format: 2 bits per
+ * pixel, 4 pixels per byte, column-major, with both axes flipped (RAM is x/y-flipped
+ * relative to the displayed image). Mirrors `make_image`/`from_pillow` in the reference
+ * driver (examples/device_driver/zhunyco/wolink_ble.py).
+ *
+ * Rows above `voffset` (present on some panel sizes) are sent as black, matching the
+ * reference driver pasting the source image at a vertical offset onto a blank canvas.
+ */
+function encodeBitmap(bitmap, metadata) {
+    const { width, height, voffset } = metadata;
+    const contentHeight = height - voffset;
+    if (bitmap.width !== width || bitmap.height !== contentHeight) {
+        throw new Error(`zhsunyco paint: bitmap is ${bitmap.width}x${bitmap.height}, device "${metadata.label}" expects ${width}x${contentHeight}`);
+    }
+    const bytesPerColumn = height / 4;
+    const data = Buffer.alloc((width * height) / 4);
+    for (let x = 0; x < width; x++) {
+        const physX = width - 1 - x;
+        for (let y = 0; y < height; y++) {
+            const srcY = y - voffset;
+            const colour = srcY >= 0 && srcY < bitmap.height ? samplePixel(bitmap, x, srcY) : 0 /* WolinkColour.Black */;
+            const physY = height - 1 - y;
+            const byteIdx = physX * bytesPerColumn + Math.floor(physY / 4);
+            const bitShift = 6 - (physY % 4) * 2;
+            data[byteIdx] |= colour << bitShift;
+        }
+    }
+    return data;
+}
+function samplePixel(bitmap, x, y) {
+    const offset = (y * bitmap.width + x) * 4;
+    return nearestColour(bitmap.data[offset], bitmap.data[offset + 1], bitmap.data[offset + 2]);
+}

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

@@ -0,0 +1,11 @@
+import { Device } from 'node-ble';
+import { Bitmap } from '../../render/types';
+import { DeviceMetadata, DiscoveredDevice, VendorDeviceConfig, VendorDriver } from '../types';
+export declare class ZhsunycoDriver implements VendorDriver {
+    readonly vendor = "zhsunyco";
+    matchesAdvertisement(name: string | undefined, manufacturerId: number | undefined): boolean;
+    metadataForPid(pid: number, hwVersion?: string): DeviceMetadata | undefined;
+    supportedDevices(): DeviceMetadata[];
+    identifyDevice(device: Device, address: string, name: string | undefined, manufacturerId: number | undefined, manufacturerData: Buffer | undefined): Promise<DiscoveredDevice>;
+    paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
+}

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'],
+    },
+];