@rhizomatics/signalk-einklabel-plugin 1.2.3 → 1.3.0-beta10

package/dist/devices/zhsunyco/index.js

@@ -2,19 +2,21 @@
 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");
 const reframe_1 = require("../../render/reframe");
+const mirror_1 = require("../../render/mirror");
+const compression_1 = require("./compression");
 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;
+/** 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 +33,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 +45,96 @@ 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 framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop"), config.mirror ?? "none");
                 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]));
+                const compress = config.compress ?? true;
+                // Upload offsets and the refresh length both count bytes of whatever's actually sent - the
+                // compressed payload when compressing, not the raw buffer it inflates back to.
+                const payload = compress ? (0, compression_1.compressWolinkBlocks)(pixelData) : pixelData;
+                for (let offset = 0; offset < payload.length; offset += UPLOAD_CHUNK_SIZE) {
+                    const chunk = payload.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
+                    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)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.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 +144,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/devices/zhsunyco/protocol.d.ts

@@ -15,6 +15,8 @@ export declare const WOLINK_CHARACTERISTIC_UUIDS: {
 export declare const COMMAND: {
     readonly uploadBlock: 42240;
     readonly refreshUncompressed: 42241;
+    /** Refresh after uploading a `compressWolinkBlocks` payload rather than the raw buffer. */
+    readonly refreshCompressed: 42242;
 };
 export interface AdvertisedDeviceInfo {
     pid: number;

package/dist/devices/zhsunyco/protocol.js

@@ -25,6 +25,8 @@ exports.WOLINK_CHARACTERISTIC_UUIDS = {
 exports.COMMAND = {
     uploadBlock: 0xa500,
     refreshUncompressed: 0xa501,
+    /** Refresh after uploading a `compressWolinkBlocks` payload rather than the raw buffer. */
+    refreshCompressed: 0xa502,
 };
 /** Decodes the 8-byte header shared by the advertising mirror and config characteristic. */
 function decodeAdvertisedInfo(data) {

package/dist/plugin.js

@@ -9,8 +9,9 @@ const discoveryCoordinator_1 = require("./devices/discoveryCoordinator");
 const bleDiscovery_1 = require("./devices/bleDiscovery");
 const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const repaintScheduler_1 = require("./repaintScheduler");
+const pluginVersion_1 = require("./pluginVersion");
 /** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
-async function runStartupScan(app, durationSeconds) {
+async function runStartupScan(app, durationSeconds, useBleApi) {
     const alreadyRunning = (0, discoveryCoordinator_1.scanInProgressSince)();
     if (alreadyRunning !== undefined) {
         const elapsedSeconds = ((Date.now() - alreadyRunning) / 1000).toFixed(0);
@@ -21,7 +22,7 @@ async function runStartupScan(app, durationSeconds) {
         app.setPluginStatus(`Scanning for ESL devices for ${durationSeconds}s...`);
     }
     const startedAt = Date.now();
-    const { foundThisScan } = await (0, discoveryCoordinator_1.ensureScan)(app, durationSeconds).catch((err) => {
+    const { foundThisScan } = await (0, discoveryCoordinator_1.ensureScan)(app, durationSeconds, useBleApi).catch((err) => {
         app.debug(`startup scan failed: ${err.message}`);
         return { foundThisScan: [] };
     });
@@ -36,7 +37,12 @@ async function runStartupScan(app, durationSeconds) {
 function createPlugin(app) {
     (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
     (0, registry_1.registerDriver)(new gicisky_1.GiciskyDriver());
+    // Present on SignalK server >= 2.32.0 (the BLE Provider/Consumer API - "BLE Manager" in the admin
+    // UI); `ServerAPI`'s own type says this is always defined, but that's only true on servers new
+    // enough to have added it - checked at runtime rather than trusted from the type.
+    const bleApiAvailable = !!app.bleApi;
     let scheduler;
+    let stopDiscoveryListener;
     let stopped = false;
     const plugin = {
         id: "signalk-einklabel-plugin",
@@ -50,28 +56,49 @@ function createPlugin(app) {
         start(config) {
             const pluginConfig = {
                 ...(0, config_1.defaultConfig)(),
-                ...config,
+                ...(0, config_1.migrateConfig)(config).config,
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
-            (0, config_1.healNestedConfig)(app);
+            (0, config_1.healStoredConfig)(app);
             stopped = false;
-            // Waits (with backoff, indefinitely on Linux) for a BLE adapter before the startup scan or the
-            // repaint scheduler touch BLE at all - see `waitForAdapter`'s doc comment on the boot-time race
-            // this covers. `stopped` is checked after, not just passed as `cancelled`, since the wait can
-            // also resolve `true` on its own right as `stop()` runs.
-            void (0, bleDiscovery_1.waitForAdapter)((message) => app.debug(message), () => stopped).then(() => {
+            const useBleApi = pluginConfig.useBleApi && bleApiAvailable;
+            if (pluginConfig.useBleApi && !bleApiAvailable) {
+                app.debug("useBleApi is enabled but this SignalK server has no BLE Manager API (requires >= 2.32.0) - falling back to direct BlueZ access");
+            }
+            app.debug(useBleApi ? "using the SignalK BLE Manager API for Bluetooth access" : "using direct BlueZ access for Bluetooth");
+            const start = () => {
                 if (stopped)
                     return;
                 if (pluginConfig.scanOnStart) {
-                    void runStartupScan(app, pluginConfig.scanDurationSeconds);
+                    void runStartupScan(app, pluginConfig.scanDurationSeconds, useBleApi);
                 }
                 scheduler = (0, repaintScheduler_1.startRepaintScheduler)(app, pluginConfig);
-            });
+            };
+            if (useBleApi) {
+                // BLE Manager already runs its own continuous scan server-side (that's what populates its own
+                // admin UI device list) - unlike direct BlueZ access below, discovery here doesn't need a
+                // bounded scan window at all, so this listens for as long as the plugin runs rather than only
+                // during `scanOnStart`/an on-demand `ALL_DEVICES` scan. See its own doc comment.
+                stopDiscoveryListener = (0, discoveryCoordinator_1.startBleApiDiscoveryListener)(app, pluginVersion_1.PLUGIN_NAME);
+                // The server/provider governs its own local-adapter readiness once BLE Manager mode owns
+                // `hci0` (or has none at all, behind a remote gateway) - waiting on a *local* BlueZ adapter
+                // here would be waiting on something this mode may never even need.
+                start();
+            }
+            else {
+                // Waits (with backoff, indefinitely on Linux) for a BLE adapter before the startup scan or
+                // the repaint scheduler touch BLE at all - see `waitForAdapter`'s doc comment on the
+                // boot-time race this covers. `stopped` is checked again inside `start()`, not just passed
+                // as `cancelled`, since the wait can also resolve `true` on its own right as `stop()` runs.
+                void (0, bleDiscovery_1.waitForAdapter)((message) => app.debug(message), () => stopped).then(start);
+            }
         },
         stop() {
             stopped = true;
             scheduler?.stop();
             scheduler = undefined;
+            stopDiscoveryListener?.();
+            stopDiscoveryListener = undefined;
             app.debug("stopped");
         },
     };

package/dist/render/mirror.d.ts

@@ -0,0 +1,11 @@
+import { Bitmap } from "./types";
+/**
+ * Flips the rendered image before it's encoded for the panel - for hardware whose RAM layout is
+ * mirrored relative to what a driver's encoder assumes (the Wolink HA integration found the 2.9"
+ * and 3.5" panels differ from the 3.7" this plugin's zhsunyco encoder was confirmed against), or a
+ * label that's simply mounted upside down (`"both"` is a 180° rotation).
+ */
+export type MirrorMode = "none" | "horizontal" | "vertical" | "both";
+export declare const MIRROR_MODES: MirrorMode[];
+/** Returns `bitmap` unchanged for `"none"`, otherwise a flipped copy. */
+export declare function mirrorBitmap(bitmap: Bitmap, mode: MirrorMode): Bitmap;

package/dist/render/mirror.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIRROR_MODES = void 0;
+exports.mirrorBitmap = mirrorBitmap;
+exports.MIRROR_MODES = ["none", "horizontal", "vertical", "both"];
+/** Returns `bitmap` unchanged for `"none"`, otherwise a flipped copy. */
+function mirrorBitmap(bitmap, mode) {
+    if (mode === "none") {
+        return bitmap;
+    }
+    const { width, height } = bitmap;
+    const flipX = mode === "horizontal" || mode === "both";
+    const flipY = mode === "vertical" || mode === "both";
+    const data = new Uint8Array(bitmap.data.length);
+    for (let y = 0; y < height; y++) {
+        const srcY = flipY ? height - 1 - y : y;
+        for (let x = 0; x < width; x++) {
+            const srcX = flipX ? width - 1 - x : x;
+            const srcOffset = (srcY * width + srcX) * 4;
+            data.set(bitmap.data.subarray(srcOffset, srcOffset + 4), (y * width + x) * 4);
+        }
+    }
+    return { width, height, data };
+}

package/dist/repaintScheduler.js

@@ -7,6 +7,7 @@ const path_1 = require("path");
 const fs_1 = require("fs");
 const config_1 = require("./config");
 const bleDiscovery_1 = require("./devices/bleDiscovery");
+const bleBackend_1 = require("./devices/bleBackend");
 const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const discoveryCoordinator_1 = require("./devices/discoveryCoordinator");
 const registry_1 = require("./devices/registry");
@@ -22,6 +23,8 @@ const pluginVersion_1 = require("./pluginVersion");
 const httpJson_1 = require("./httpJson");
 const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
+/** Pause between paint attempts - see `withRetries`' `delayMs`. */
+const PAINT_RETRY_DELAY_MS = 5000;
 const RESOURCES_API_PATH = "/signalk/v2/api/resources";
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own
@@ -172,7 +175,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
 }
 function clearForceRepaint(app, friendlyName) {
     const current = (0, config_1.readCurrentConfig)(app);
-    const devices = (current.devices ?? []).map((device) => device.friendlyName === friendlyName ? { ...device, forceRepaint: false } : device);
+    const devices = (current.devices ?? []).map((device) => device.friendlyName === friendlyName ? { ...device, advanced: { ...device.advanced, forceRepaint: false } } : device);
     app.savePluginOptions({ ...current, devices }, (err) => {
         if (err)
             app.debug(`failed to clear forceRepaint for "${friendlyName}": ${err.message}`);
@@ -200,7 +203,7 @@ async function resolveTargets(app, config, device) {
         let records = (0, discoveredDevicesStore_1.loadDiscoveredDevices)(app);
         if (Object.keys(records).length === 0) {
             app.debug(`"${device.friendlyName}": device is "${config_1.ALL_DEVICES}" and nothing discovered yet - scanning for ${config.scanDurationSeconds}s`);
-            records = (await (0, discoveryCoordinator_1.ensureScan)(app, config.scanDurationSeconds)).merged;
+            records = (await (0, discoveryCoordinator_1.ensureScan)(app, config.scanDurationSeconds, config.useBleApi && !!app.bleApi)).merged;
         }
         const targets = [];
         for (const record of Object.values(records)) {
@@ -306,7 +309,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
         // scheduled tick" (e.g. a regenerated forecast) is the whole point of one - which is exactly why a
         // provider-backed device should use `repaintTrigger: "interval"`, not `subscription`, for
         // cost/battery reasons (each repaint may be a paid API call on the provider's side).
-        if (!provider && !templateChanged && !dataChanged && !device.forceRepaint) {
+        if (!provider && !templateChanged && !dataChanged && !device.advanced?.forceRepaint) {
             app.debug(`${label}: data unchanged, skipping repaint`);
             return;
         }
@@ -324,7 +327,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             ? await provider.render({ templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours })
             : await renderer.render(templatePath, renderContext, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
         succeeded = true;
-        repaintReason = device.forceRepaint
+        repaintReason = device.advanced?.forceRepaint
             ? "forced"
             : provider
                 ? "provider-rendered"
@@ -343,15 +346,29 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
         });
         bitmap = await renderer.render(fallbackPath, { meta: { repainted: new Date().toISOString(), plugin_version: pluginVersion_1.PLUGIN_VERSION, description: device.description ?? "" } }, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
     }
-    const connectTimeoutMs = config.paintConnectTimeoutSeconds * 1000;
-    await (0, bleDiscovery_1.withRetries)(config.paintRetries, async (attempt) => {
-        if (attempt > 1) {
-            app.debug(`${label}: attempting paint ${attempt}/${config.paintRetries}`);
-        }
+    const connectTimeoutMs = (device.advanced?.paintConnectTimeoutSeconds ?? config.paintConnectTimeoutSeconds) * 1000;
+    const gattBackend = config.useBleApi && app.bleApi ? (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME) : undefined;
+    const attempts = Math.max(1, device.advanced?.paintRetries ?? config.paintRetries);
+    const paintWithRetries = () => (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
+        app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
         const startedAt = Date.now();
-        await driver.paint(bitmap, { address, aesKey: device.aesKey, connectTimeoutMs, reframe: device.reframe });
+        await driver.paint(bitmap, {
+            address,
+            pid: target.pid,
+            aesKey: device.advanced?.aesKey,
+            connectTimeoutMs,
+            reframe: device.reframe,
+            mirror: device.advanced?.mirror,
+            compress: device.advanced?.compress,
+            compressionFormat: device.advanced?.compressionFormat,
+            gattBackend,
+        });
         paintDurationMs = Date.now() - startedAt;
+    }, {
+        delayMs: PAINT_RETRY_DELAY_MS,
+        onError: (err, attempt) => app.debug(`${label}: paint attempt ${attempt}/${attempts} failed: ${err.message}`),
     });
+    await (gattBackend ? (0, bleBackend_1.exclusiveBleManagerAccess)(paintWithRetries) : paintWithRetries());
     (0, discoveredDevicesStore_1.touchDiscoveredDevice)(app, { address, vendor: target.vendor, pid: target.pid, hwVersion: target.hwVersion, metadata });
     // Only a successful render counts as "repainted" for dedup/catch-up purposes - a failure must not be
     // recorded here (see this function's doc comment on why).
@@ -391,7 +408,7 @@ function startRepaintScheduler(app, config) {
         // A single `forceRepaint` flag covers every target under `ALL_DEVICES` too - only clear it once
         // every target has actually succeeded, so a target that failed still gets forced again next time
         // instead of quietly reverting to ordinary hash-based dedup.
-        if (device.forceRepaint && results.every((result) => result.status === "fulfilled")) {
+        if (device.advanced?.forceRepaint && results.every((result) => result.status === "fulfilled")) {
             clearForceRepaint(app, device.friendlyName);
         }
     };
@@ -438,7 +455,7 @@ function startRepaintScheduler(app, config) {
     // still avoids a redundant paint once targets are resolved.
     const startupCheckTimer = setTimeout(() => {
         for (const device of config.devices) {
-            if (device.repaintTrigger === "interval" && !device.forceRepaint && device.device !== config_1.ALL_DEVICES) {
+            if (device.repaintTrigger === "interval" && !device.advanced?.forceRepaint && device.device !== config_1.ALL_DEVICES) {
                 const hours = device.intervalHours ?? 1;
                 const minute = device.intervalMinute ?? 0;
                 const dueSlot = mostRecentScheduledSlot(new Date(), hours, minute);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.2.3",
+  "version": "1.3.0-beta10",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",
@@ -64,7 +64,7 @@
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
-    "@signalk/server-api": "^2.31.0",
+    "@signalk/server-api": "^2.32.0",
     "@types/luxon": "^3.7.1",
     "@types/node": "^26.4.0",
     "@types/pngjs": "^6.0.5",
@@ -75,7 +75,7 @@
     "typescript": "^5.5.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "signalk": {
     "displayName": "eInk Label Displays",