@rhizomatics/signalk-einklabel-plugin 1.2.2 → 1.3.0-beta1

package/dist/devices/gicisky/index.js

@@ -1,14 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GiciskyDriver = void 0;
-const bleDiscovery_1 = require("../bleDiscovery");
+const bleBackend_1 = require("../bleBackend");
 const metadata_1 = require("./metadata");
 const layout_1 = require("./layout");
 const encode_1 = require("./encode");
 const reframe_1 = require("../../render/reframe");
 const protocol_1 = require("./protocol");
-const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
-/** How long to actively rescan for a fresh advertisement when the cached one is missing/stale - see `waitForManufacturerData`. */
+/** How long to actively rescan for a fresh advertisement when the cached one is missing/stale - see `BleBackend.waitForManufacturerData`. */
 const MANUFACTURER_DATA_RESCAN_TIMEOUT_MS = 15000;
 const DEFAULT_PAINT_CONNECT_TIMEOUT_MS = 60000;
 const ACK_TIMEOUT_MS = 15000;
@@ -30,7 +29,7 @@ class GiciskyDriver {
     supportedDevices() {
         return metadata_1.GICISKY_PID_METADATA;
     }
-    async identifyDevice(device, address, name, manufacturerId, manufacturerData) {
+    async identifyDevice({ address, name, manufacturerId, manufacturerData, rssi, }) {
         const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
         return {
             address,
@@ -40,128 +39,140 @@ class GiciskyDriver {
             metadata: info ? this.metadataForPid(info.deviceId) : undefined,
             manufacturerId,
             batteryMv: info?.batteryMv,
-            rssi: await device
-                .getRSSI()
-                .then((value) => (value === undefined ? undefined : Number(value)))
-                .catch(() => undefined),
+            rssi,
         };
     }
     async paint(bitmap, config) {
-        const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+        const backend = config.gattBackend ?? (0, bleBackend_1.nodeBleBackend)();
+        /**
+         * Unlike zhsunyco, there's no GATT characteristic that reports the device's PID on demand -
+         * the only source for it is the advertisement. That cache can be empty or stale (e.g. nothing
+         * has actively scanned since the adapter/provider last restarted) even though a connect below
+         * would succeed instantly via BlueZ's/the BLE Manager's own device cache - so rescan for a fresh
+         * advertisement here rather than failing on the first read.
+         */
+        const manufacturerData = await backend.waitForManufacturerData(config.address, protocol_1.GICISKY_MANUFACTURER_ID, MANUFACTURER_DATA_RESCAN_TIMEOUT_MS);
+        const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
+        const metadata = config.modelOverride
+            ? { pid: info?.deviceId ?? 0, ...config.modelOverride }
+            : info
+                ? this.metadataForPid(info.deviceId)
+                : undefined;
+        if (!metadata) {
+            throw new Error(info === undefined
+                ? "gicisky device isn't advertising - rescanned but got nothing back (out of range, asleep, or already connected " +
+                    "elsewhere) - pass --width/--height/--voffset/--colours to describe it manually"
+                : `gicisky device reports unrecognised deviceId 0x${info.deviceId.toString(16).padStart(4, "0")} - ` +
+                    "pass --width/--height/--voffset/--colours to describe it manually");
+        }
+        const layout = (info && layout_1.GICISKY_PID_LAYOUT[info.deviceId]) || (0, layout_1.defaultLayoutFor)(metadata.colours);
+        const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop");
+        const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout);
+        const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
         try {
-            const adapter = await bluetooth.defaultAdapter();
-            const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, config.address, DEVICE_DISCOVERY_TIMEOUT_MS);
-            /**
-             * Unlike zhsunyco, there's no GATT characteristic that reports the device's PID on demand -
-             * the only source for it is the advertisement, cached on the `Device` object by BlueZ from
-             * the last time it was seen (the same cache `identifyDevice`/a scan reads, just without
-             * connecting first - see `forEachAdvertisedDevice` in `bleDiscovery.ts`). That cache can be
-             * empty or stale (e.g. nothing has actively scanned since `bluetoothd` last restarted) even
-             * though `getOrDiscoverDevice` above found the device instantly via BlueZ's own cache of
-             * *devices* - so rescan for a fresh advertisement here rather than failing on the first read.
-             */
-            const manufacturerData = await (0, bleDiscovery_1.waitForManufacturerData)(adapter, device, protocol_1.GICISKY_MANUFACTURER_ID, MANUFACTURER_DATA_RESCAN_TIMEOUT_MS);
-            const info = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
-            const metadata = config.modelOverride
-                ? { pid: info?.deviceId ?? 0, ...config.modelOverride }
-                : info
-                    ? this.metadataForPid(info.deviceId)
-                    : undefined;
-            if (!metadata) {
-                throw new Error(info === undefined
-                    ? "gicisky device isn't advertising - rescanned but got nothing back (out of range, asleep, or already connected " +
-                        "elsewhere) - pass --width/--height/--voffset/--colours to describe it manually"
-                    : `gicisky device reports unrecognised deviceId 0x${info.deviceId.toString(16).padStart(4, "0")} - ` +
-                        "pass --width/--height/--voffset/--colours to describe it manually");
-            }
-            const layout = (info && layout_1.GICISKY_PID_LAYOUT[info.deviceId]) || (0, layout_1.defaultLayoutFor)(metadata.colours);
-            const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop");
-            const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout);
-            await (0, bleDiscovery_1.connectWithTimeout)(device, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+            const { cmdServiceUuid, cmdUuid, imgServiceUuid, imgUuid } = await findCommandAndImageCharacteristics(conn);
+            const ack = new AckChannel();
+            await conn.startNotifications(cmdServiceUuid, cmdUuid, ack.onNotify);
             try {
-                const gatt = await device.gatt();
-                const { cmd, img } = await findCommandAndImageCharacteristics(gatt);
-                await cmd.startNotifications();
-                try {
-                    const startAck = await writeAndAwaitAck(cmd, cmd, Buffer.from([0x01]));
-                    const chunkSize = ((0, protocol_1.decodeBlockSize)(startAck) ?? DEFAULT_BLOCK_SIZE) - PART_INDEX_HEADER_LENGTH;
-                    await writeAndAwaitAck(cmd, cmd, (0, protocol_1.writeScreenCommand)(payload.length, layout.packing === "chunked"));
-                    const startImageAck = await writeAndAwaitAck(cmd, cmd, Buffer.from([0x03]));
-                    const started = (0, protocol_1.decodeTransferAck)(startImageAck);
-                    if (!started?.ok) {
-                        throw new Error(`gicisky device rejected start-image-transfer request: ${startImageAck.toString("hex")}`);
+                const startAck = await writeAndAwaitAck(conn, cmdServiceUuid, cmdUuid, Buffer.from([0x01]), ack);
+                const chunkSize = ((0, protocol_1.decodeBlockSize)(startAck) ?? DEFAULT_BLOCK_SIZE) - PART_INDEX_HEADER_LENGTH;
+                await writeAndAwaitAck(conn, cmdServiceUuid, cmdUuid, (0, protocol_1.writeScreenCommand)(payload.length, layout.packing === "chunked"), ack);
+                const startImageAck = await writeAndAwaitAck(conn, cmdServiceUuid, cmdUuid, Buffer.from([0x03]), ack);
+                const started = (0, protocol_1.decodeTransferAck)(startImageAck);
+                if (!started?.ok) {
+                    throw new Error(`gicisky device rejected start-image-transfer request: ${startImageAck.toString("hex")}`);
+                }
+                let part = started.nextPart;
+                let lastPart = -1;
+                let repeats = 0;
+                while (part * chunkSize < payload.length) {
+                    const chunk = payload.subarray(part * chunkSize, Math.min(part * chunkSize + chunkSize, payload.length));
+                    const ackData = await writeAndAwaitAck(conn, imgServiceUuid, imgUuid, (0, protocol_1.imageChunkPacket)(part, chunk), ack);
+                    const decoded = (0, protocol_1.decodeTransferAck)(ackData);
+                    if (!decoded?.ok) {
+                        throw new Error(`gicisky device reported an error transferring image part ${part}: ${ackData.toString("hex")}`);
                     }
-                    let part = started.nextPart;
-                    let lastPart = -1;
-                    let repeats = 0;
-                    while (part * chunkSize < payload.length) {
-                        const chunk = payload.subarray(part * chunkSize, Math.min(part * chunkSize + chunkSize, payload.length));
-                        const ack = await writeAndAwaitAck(img, cmd, (0, protocol_1.imageChunkPacket)(part, chunk));
-                        const decoded = (0, protocol_1.decodeTransferAck)(ack);
-                        if (!decoded?.ok) {
-                            throw new Error(`gicisky device reported an error transferring image part ${part}: ${ack.toString("hex")}`);
-                        }
-                        if (decoded.nextPart === lastPart) {
-                            repeats++;
-                            if (repeats >= MAX_STALLED_REPEATS) {
-                                throw new Error(`gicisky image transfer stalled - device kept re-requesting part ${decoded.nextPart}`);
-                            }
+                    if (decoded.nextPart === lastPart) {
+                        repeats++;
+                        if (repeats >= MAX_STALLED_REPEATS) {
+                            throw new Error(`gicisky image transfer stalled - device kept re-requesting part ${decoded.nextPart}`);
                         }
-                        else {
-                            repeats = 0;
-                            lastPart = decoded.nextPart;
-                        }
-                        part = decoded.nextPart;
                     }
-                }
-                finally {
-                    await cmd.stopNotifications().catch(() => { });
+                    else {
+                        repeats = 0;
+                        lastPart = decoded.nextPart;
+                    }
+                    part = decoded.nextPart;
                 }
             }
             finally {
-                await device.disconnect();
+                await conn.stopNotifications(cmdServiceUuid, cmdUuid).catch(() => { });
             }
         }
         finally {
-            destroy();
+            await conn.disconnect();
         }
     }
 }
 exports.GiciskyDriver = GiciskyDriver;
+/**
+ * Single-slot "await the next notification" dispatcher - the gicisky protocol is strictly
+ * request/response (never more than one write in flight), so a persistent `startNotifications`
+ * callback (`GattConnection`'s shape, unlike node-ble's per-call `.once("valuechanged")`) just needs
+ * to hand its next delivery to whichever `waitForAck` call is currently pending. Mirrors how
+ * signalk-bluetti-plugin's `ProtocolSession.feed()` dispatches notification bytes to a single
+ * pending request.
+ */
+class AckChannel {
+    constructor() {
+        this.onNotify = (data) => {
+            const pending = this.pending;
+            if (!pending)
+                return;
+            this.pending = undefined;
+            clearTimeout(pending.timer);
+            pending.resolve(data);
+        };
+    }
+    waitForAck(timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending = undefined;
+                reject(new Error("gicisky device did not acknowledge in time"));
+            }, timeoutMs);
+            this.pending = { resolve, timer };
+        });
+    }
+}
+/** Writes `data` to `(writeServiceUuid, writeUuid)`, then awaits the next ack delivered to `ack`. */
+async function writeAndAwaitAck(conn, writeServiceUuid, writeUuid, data, ack) {
+    const pending = ack.waitForAck(ACK_TIMEOUT_MS);
+    await conn.write(writeServiceUuid, writeUuid, data, false);
+    return pending;
+}
 /**
  * Walks every service whose UUID starts `0000f`, collecting their characteristics and sorting by
  * 16-bit UUID value - mirrors both reference drivers, which locate their command/image
  * characteristics this way rather than by a hardcoded service UUID (see `protocol.ts`).
  */
-async function findCommandAndImageCharacteristics(gatt) {
+async function findCommandAndImageCharacteristics(conn) {
     const candidates = [];
-    for (const serviceUuid of await gatt.services()) {
-        if (!serviceUuid.toLowerCase().startsWith(protocol_1.CANDIDATE_SERVICE_UUID_PREFIX)) {
+    for (const service of await conn.discoverServices()) {
+        if (!service.uuid.toLowerCase().startsWith(protocol_1.CANDIDATE_SERVICE_UUID_PREFIX)) {
             continue;
         }
-        const service = await gatt.getPrimaryService(serviceUuid);
-        for (const charUuid of await service.characteristics()) {
-            candidates.push({ uuid: charUuid, char: await service.getCharacteristic(charUuid) });
+        for (const characteristic of service.characteristics) {
+            candidates.push({ serviceUuid: service.uuid, uuid: characteristic.uuid });
         }
     }
     candidates.sort((a, b) => parseInt(a.uuid.slice(4, 8), 16) - parseInt(b.uuid.slice(4, 8), 16));
     if (candidates.length < 2) {
         throw new Error(`gicisky device exposes ${candidates.length} candidate characteristic(s) under a "0000f..." service, expected at least 2`);
     }
-    return { cmd: candidates[0].char, img: candidates[1].char };
-}
-/** Writes `data` to `writeChar`, then awaits the next notification on `notifyChar` (which may be the same characteristic). */
-function writeAndAwaitAck(writeChar, notifyChar, data) {
-    const ack = new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            notifyChar.removeListener("valuechanged", onValue);
-            reject(new Error("gicisky device did not acknowledge in time"));
-        }, ACK_TIMEOUT_MS);
-        function onValue(value) {
-            clearTimeout(timer);
-            resolve(value);
-        }
-        notifyChar.once("valuechanged", onValue);
-    });
-    return writeChar.writeValueWithoutResponse(data).then(() => ack);
+    return {
+        cmdServiceUuid: candidates[0].serviceUuid,
+        cmdUuid: candidates[0].uuid,
+        imgServiceUuid: candidates[1].serviceUuid,
+        imgUuid: candidates[1].uuid,
+    };
 }

package/dist/devices/types.d.ts

@@ -1,6 +1,7 @@
-import { Device } from "@naugehyde/node-ble";
 import { Bitmap } from "../render/types";
 import { ReframeMode } from "../render/reframe";
+import { BleBackend } from "./bleBackend";
+import { GattConnection } from "./gattConnection";
 export type Colour = "black" | "white" | "red" | "yellow";
 /**
  * Static facts about one device model, keyed by (vendor, pid) by the registry —
@@ -60,6 +61,14 @@ export interface VendorDeviceConfig {
     connectTimeoutMs?: number;
     /** How to fit the bitmap onto the panel when its size doesn't already match - see `ReframeMode`. Defaults to `"crop"` - a live label showing *something*, even off-size, beats a repaint that just fails outright; pass `"fixed"` explicitly to get the old reject-the-mismatch behaviour back. */
     reframe?: ReframeMode;
+    /**
+     * How `paint()` reaches the device's BLE hardware - omitted (always true for the CLI, which has no
+     * `ServerAPI`/`app.bleApi` to source one from) means direct BlueZ access via a fresh
+     * `nodeBleBackend()` (`bleBackend.ts`). The SignalK plugin (`plugin.ts`/`repaintScheduler.ts`) passes
+     * a `bleApiBackend()` here instead when the user has opted into the SignalK BLE Manager API
+     * (`PluginConfig.useBleApi`) and the server offers `app.bleApi`.
+     */
+    gattBackend?: BleBackend;
 }
 export interface VendorDriver {
     vendor: string;
@@ -70,12 +79,23 @@ export interface VendorDriver {
     /** 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.
+     * Identifies one device the shared caller (`discoveryCoordinator.ts`'s `runScan`, backed by either
+     * `forEachAdvertisedDevice` over direct BlueZ or the BLE Manager API's advertisement stream) 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.
+     *
+     * `connect` opens a `GattConnection` to this device on whichever backend the scan is using - call it
+     * lazily, only when the advertisement alone doesn't carry enough to identify the device (e.g.
+     * zhsunyco's battery/config read fallback); most matches never need it.
      */
-    identifyDevice(device: Device, address: string, name: string | undefined, manufacturerId: number | undefined, manufacturerData: Buffer | undefined): Promise<DiscoveredDevice>;
+    identifyDevice(advertisement: {
+        address: string;
+        name: string | undefined;
+        manufacturerId: number | undefined;
+        manufacturerData: Buffer | undefined;
+        rssi: number | undefined;
+    }, connect: () => Promise<GattConnection>): 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/zhsunyco/index.d.ts

@@ -1,11 +1,17 @@
-import { Device } from "@naugehyde/node-ble";
 import { Bitmap } from "../../render/types";
 import { DeviceMetadata, DiscoveredDevice, VendorDeviceConfig, VendorDriver } from "../types";
+import { GattConnection } from "../gattConnection";
 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>;
+    identifyDevice({ address, name, manufacturerId, manufacturerData, rssi, }: {
+        address: string;
+        name: string | undefined;
+        manufacturerId: number | undefined;
+        manufacturerData: Buffer | undefined;
+        rssi: number | undefined;
+    }, connect: () => Promise<GattConnection>): Promise<DiscoveredDevice>;
     paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
 }

package/dist/devices/zhsunyco/index.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZhsunycoDriver = void 0;
 const bleDiscovery_1 = require("../bleDiscovery");
+const bleBackend_1 = require("../bleBackend");
 const pluginVersion_1 = require("../../pluginVersion");
 const metadata_1 = require("./metadata");
 const encode_1 = require("./encode");
@@ -12,9 +13,8 @@ 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;
+/** Bounds `readDeviceDetails`' whole connect+read attempt during a scan - see its doc comment. */
+const IDENTIFY_READ_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 = 60000;
 class ZhsunycoDriver {
@@ -31,9 +31,9 @@ class ZhsunycoDriver {
     supportedDevices() {
         return metadata_1.ZHSUNYCO_PID_METADATA;
     }
-    async identifyDevice(device, address, name, manufacturerId, manufacturerData) {
+    async identifyDevice({ address, name, manufacturerId, manufacturerData, rssi, }, connect) {
         const advertisedInfo = manufacturerData ? (0, protocol_1.decodeAdvertisedInfo)(manufacturerData) : undefined;
-        const { info, batteryMv } = await readDeviceDetails(device, address, advertisedInfo);
+        const { info, batteryMv } = await readDeviceDetails(address, advertisedInfo, connect);
         return {
             address,
             name,
@@ -43,99 +43,92 @@ class ZhsunycoDriver {
             metadata: info ? this.metadataForPid(info.pid, info.hwVersion) : undefined,
             manufacturerId,
             batteryMv,
-            rssi: await device
-                .getRSSI()
-                .then((value) => (value === undefined ? undefined : Number(value)))
-                .catch(() => undefined),
+            rssi,
         };
     }
     async paint(bitmap, config) {
         const aesKey = (0, protocol_1.resolveAesKey)(config.aesKey);
-        const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+        const backend = config.gattBackend ?? (0, bleBackend_1.nodeBleBackend)();
+        const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
         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);
+            const info = (0, protocol_1.decodeAdvertisedInfo)(await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config));
+            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) => {
+                conn
+                    .startNotifications(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.status, (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`));
+                    }
+                })
+                    .catch(reject);
+            });
             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));
+                const challenge = await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate);
+                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate, (0, protocol_1.authResponse)(challenge, aesKey), false);
                 await (0, bleDiscovery_1.sleep)(AUTH_SETTLE_DELAY_MS);
                 const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop");
                 const pixelData = (0, encode_1.encodeBitmap)(framed, 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 conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), true);
                     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)]);
+                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(protocol_1.COMMAND.refreshUncompressed, pixelData.length), true);
+                // `Promise.race` can't cancel its loser, so once `statusReceived` settles (the common case)
+                // this timer would otherwise sit alive for the rest of its 60s regardless - see the identical
+                // reasoning on `readDeviceDetails`'s own race, below.
+                let statusTimer;
+                const statusTimeout = new Promise((resolve) => {
+                    statusTimer = setTimeout(resolve, STATUS_WAIT_TIMEOUT_MS);
+                });
+                try {
+                    await Promise.race([statusReceived, statusTimeout]);
+                }
+                finally {
+                    clearTimeout(statusTimer);
+                }
             }
             finally {
-                await device.disconnect();
+                await conn.stopNotifications(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.status).catch(() => { });
             }
         }
         finally {
-            destroy();
+            await conn.disconnect();
         }
     }
 }
 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
+ * when the advertisement didn't carry decodable manufacturer data - a scan matched purely by 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, address, advertisedInfo) {
+async function readDeviceDetails(address, advertisedInfo, connect) {
     const fallback = { info: advertisedInfo, batteryMv: undefined };
     const read = async () => {
+        let conn;
         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();
+            conn = await connect();
+            const batteryMv = (0, protocol_1.decodeBatteryMv)(await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.battery));
+            let info = advertisedInfo;
+            if (!info) {
+                info = (0, protocol_1.decodeAdvertisedInfo)(await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config));
             }
+            return { info, batteryMv };
         }
         catch (err) {
             // Swallowed rather than thrown - a device that refuses this connect (e.g. busy elsewhere,
@@ -145,16 +138,27 @@ async function readDeviceDetails(device, address, advertisedInfo) {
             console.error(`${pluginVersion_1.PLUGIN_NAME}: zhsunyco [${address}]: battery/config read failed: ${err.message}`);
             return fallback;
         }
+        finally {
+            await conn?.disconnect().catch(() => { });
+        }
     };
-    // `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 * 3).then(() => {
-            console.error(`${pluginVersion_1.PLUGIN_NAME}: zhsunyco [${address}]: battery/config read timed out after ${SCAN_CONNECT_TIMEOUT_MS * 2}ms`);
-            return fallback;
-        }),
-    ]);
+    // A GATT call has no timeout of its own - 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). `Promise.race` alone can't cancel its loser, so a `read()`
+    // that settles fast (e.g. `connect` rejecting immediately because the device is busy elsewhere -
+    // exactly the case this function's own doc comment covers) would otherwise leave this timer running
+    // for the rest of its 30s regardless - harmless in the end, but needless to hold onto that long.
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            console.error(`${pluginVersion_1.PLUGIN_NAME}: zhsunyco [${address}]: battery/config read timed out after ${IDENTIFY_READ_TIMEOUT_MS * 2}ms`);
+            resolve(fallback);
+        }, IDENTIFY_READ_TIMEOUT_MS * 3);
+    });
+    try {
+        return await Promise.race([read(), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }

package/dist/email/emailSender.d.ts

@@ -0,0 +1,27 @@
+import { EmailConfig } from "../config";
+import { Bitmap } from "../render/types";
+import { FieldRow } from "../render/fieldsTable";
+/** Either the SVG template's field-by-field table (`buildFieldsTable`), a `TemplateProvider`'s own rendered-content text (`describeContent`), or neither (a provider offered no `describeContent`). */
+export type EmailContentBody = {
+    kind: "table";
+    rows: FieldRow[];
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "none";
+};
+export interface LabelEmailContent {
+    friendlyName: string;
+    description?: string;
+    bitmap: Bitmap;
+    body: EmailContentBody;
+}
+/**
+ * Renders and sends one device's repaint as an email - a PNG attachment (also shown inline via a `cid`
+ * reference), the same field-by-field table `esl-cli fields` shows for a hand-authored SVG template (or
+ * a `TemplateProvider`'s own rendered-content text for something like a GenAI prompt - see `body`), and a
+ * link back to the docs site. Called from `considerRepaint` (`../repaintScheduler.ts`) whenever a
+ * device's `emailTo` is set and its render succeeds.
+ */
+export declare function sendLabelEmail(emailConfig: EmailConfig, to: string, content: LabelEmailContent): Promise<void>;