@rhizomatics/signalk-einklabel-plugin 1.3.0-beta13 → 1.3.0-beta14

package/dist/cli/index.js

@@ -291,6 +291,7 @@ exports.program
             mirror: parseMirrorMode(opts.mirror),
             compress: opts.compress,
             compressionFormat: parseCompressionFormat(opts.compressionFormat),
+            log: log_1.logDebug,
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);

package/dist/devices/bleBackend.js

@@ -168,6 +168,17 @@ async function ensureDeviceVisible(bleApi, pluginId, address, timeoutMs) {
         throw new Error(`device ${address} isn't visible to the SignalK BLE Manager yet (out of range, asleep, or never seen) after waiting ${timeoutMs}ms`);
     }
 }
+/**
+ * Upper bound on each BLE Manager release/disconnect call this plugin waits on. Neither has a timeout
+ * of its own, and a release has to disconnect the device, which can wait on a Bluetooth link that's
+ * already gone - left unbounded, one stuck release wedges every later paint behind it (see
+ * `exclusiveBleManagerAccess`).
+ */
+const CLEANUP_TIMEOUT_MS = 10000;
+/** Waits for a cleanup call for at most `CLEANUP_TIMEOUT_MS`, ignoring its outcome - cleanup is best-effort. */
+async function boundedCleanup(...calls) {
+    await (0, bleDiscovery_1.withDeadline)(Promise.allSettled(calls), CLEANUP_TIMEOUT_MS, "BLE Manager cleanup").catch((err) => console.error(`${pluginVersion_1.PLUGIN_NAME}: ${err.message} - carrying on`));
+}
 /** Upper bound on how long a timed-out `bleApi.connectGATT()` is given to settle server-side before a retry - see `bleApiBackend`. */
 const CONNECT_SETTLE_GRACE_MS = 30000;
 let bleManagerQueue = Promise.resolve();
@@ -194,7 +205,7 @@ function bleApiBackend(bleApi, pluginId) {
             // registered under our own pluginId, which would otherwise block this connect with
             // "already claimed" until the server restarts - see signalk-bluetti-plugin's BleManagerDevice
             // for the same defensive call. A no-op if we don't currently hold the claim.
-            await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+            await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
             await ensureDeviceVisible(bleApi, pluginId, address, DEVICE_DISCOVERY_TIMEOUT_MS);
             const connecting = bleApi.connectGATT(address, pluginId);
             let timedOut = false;
@@ -210,7 +221,7 @@ function bleApiBackend(bleApi, pluginId) {
                 // disconnect again. The release is awaited (only the late disconnect is left in the
                 // background) so a caller retrying straight away - `withRetries` - can't race it with a new
                 // `connectGATT()` and get rejected with "has a GATT claim in progress" for its trouble.
-                await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+                await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
                 // ...except a claim still *connecting* isn't in the server's claim table yet, only its pending
                 // set, which `releaseGATTDevice` doesn't touch - so while the server's own connect is still in
                 // flight, a retry's `connectGATT()` is rejected outright with "has a GATT claim in progress".
@@ -220,7 +231,7 @@ function bleApiBackend(bleApi, pluginId) {
                     (0, bleDiscovery_1.sleep)(Math.min(timeoutMs, CONNECT_SETTLE_GRACE_MS)).then(() => undefined),
                 ]);
                 if (late) {
-                    await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), late.disconnect()]);
+                    await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId), late.disconnect());
                 }
                 else {
                     void connecting.then((c) => c.disconnect()).catch(() => { });
@@ -231,7 +242,7 @@ function bleApiBackend(bleApi, pluginId) {
                 // Belt-and-suspenders, matching the timeout-cleanup above: `releaseGATTDevice` is the
                 // authoritative claim release, `disconnect()` a secondary teardown of this specific handle -
                 // do both regardless of which (if either) itself hangs or rejects.
-                await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), conn.disconnect()]);
+                await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId), conn.disconnect());
             });
         },
         async waitForManufacturerData(address, manufacturerId, timeoutMs) {
@@ -246,7 +257,7 @@ function bleApiBackend(bleApi, pluginId) {
             // this wait forever, since nothing else in this path ever calls `connectGatt` (and so never gets a
             // chance to release the stale claim) unless a fresh advertisement shows up first. A no-op if we
             // don't currently hold the claim.
-            await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+            await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
             return new Promise((resolve) => {
                 const timer = setTimeout(() => {
                     unsubscribe();

package/dist/devices/bleDiscovery.d.ts

@@ -40,6 +40,11 @@ export declare function forEachAdvertisedDevice(adapter: Adapter, fn: (advertise
  * last one that's eventually thrown - an early attempt's error is often the real cause, with later
  * ones just fallout from it.
  */
+/**
+ * Rejects with `${what} timed out after ${ms}ms` if `promise` hasn't settled by then. The underlying
+ * work can't be cancelled - this only lets the caller stop waiting for it.
+ */
+export declare function withDeadline<T>(promise: Promise<T>, ms: number, what: string): Promise<T>;
 export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>, { delayMs, onError }?: {
     delayMs?: number;
     onError?: (err: unknown, attempt: number) => void;

package/dist/devices/bleDiscovery.js

@@ -4,6 +4,7 @@ exports.sleep = sleep;
 exports.createBluetooth = createBluetooth;
 exports.getManufacturerId = getManufacturerId;
 exports.forEachAdvertisedDevice = forEachAdvertisedDevice;
+exports.withDeadline = withDeadline;
 exports.withRetries = withRetries;
 exports.withDiscovery = withDiscovery;
 exports.connectWithTimeout = connectWithTimeout;
@@ -74,6 +75,23 @@ async function forEachAdvertisedDevice(adapter, fn) {
  * last one that's eventually thrown - an early attempt's error is often the real cause, with later
  * ones just fallout from it.
  */
+/**
+ * Rejects with `${what} timed out after ${ms}ms` if `promise` hasn't settled by then. The underlying
+ * work can't be cancelled - this only lets the caller stop waiting for it.
+ */
+async function withDeadline(promise, ms, what) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms);
+    });
+    promise.catch(() => { }); // observed here too, so losing the race never surfaces as an unhandled rejection
+    try {
+        return await Promise.race([promise, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
     const total = Math.max(1, attempts);
     let lastErr;

package/dist/devices/gicisky/index.js

@@ -73,7 +73,10 @@ class GiciskyDriver {
         const layout = (0, layout_1.withCompressionFormat)((pid !== undefined && layout_1.GICISKY_PID_LAYOUT[pid]) || (0, layout_1.defaultLayoutFor)(metadata.colours), config.compressionFormat ?? "auto", metadata.colours);
         const framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop"), config.mirror ?? "none");
         const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout, config.compress ?? true);
+        const log = config.log ?? (() => { });
+        log("connecting");
         const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+        log("connected");
         try {
             const { cmdServiceUuid, cmdUuid, imgServiceUuid, imgUuid } = await findCommandAndImageCharacteristics(conn);
             const ack = new AckChannel();
@@ -87,6 +90,7 @@ class GiciskyDriver {
                 if (!started?.ok) {
                     throw new Error(`gicisky device rejected start-image-transfer request: ${startImageAck.toString("hex")}`);
                 }
+                log(`uploading ${payload.length} bytes in ${Math.ceil(payload.length / chunkSize)} parts`);
                 let part = started.nextPart;
                 let lastPart = -1;
                 let repeats = 0;
@@ -115,6 +119,7 @@ class GiciskyDriver {
                     }
                     part = decoded.nextPart;
                 }
+                log("upload complete");
             }
             finally {
                 await conn.stopNotifications(cmdServiceUuid, cmdUuid).catch(() => { });

package/dist/devices/types.d.ts

@@ -83,6 +83,11 @@ export interface VendorDeviceConfig {
     compress?: boolean;
     /** Overrides the model's own wire format - see `CompressionFormat`. Defaults to `"auto"`. */
     compressionFormat?: CompressionFormat;
+    /**
+     * Receives one line per paint step (connecting, connected, uploading, ...), so a paint that stalls
+     * shows in the log where it stopped. Omitted means no step logging.
+     */
+    log?: (message: string) => void;
     /**
      * 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

package/dist/devices/zhsunyco/index.js

@@ -50,8 +50,11 @@ class ZhsunycoDriver {
     }
     async paint(bitmap, config) {
         const aesKey = (0, protocol_1.resolveAesKey)(config.aesKey);
+        const log = config.log ?? (() => { });
         const backend = config.gattBackend ?? (0, bleBackend_1.nodeBleBackend)();
+        log("connecting");
         const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+        log("connected");
         try {
             const info = (0, protocol_1.decodeAdvertisedInfo)(await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config));
             if (!info) {
@@ -79,27 +82,34 @@ class ZhsunycoDriver {
                 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);
+                log("authenticated");
                 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);
                 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;
+                log(`uploading ${payload.length} bytes${compress ? ` (compressed from ${pixelData.length})` : ""} in ` +
+                    `${Math.ceil(payload.length / UPLOAD_CHUNK_SIZE)} writes`);
                 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 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);
+                log("refresh sent, waiting for the label to finish");
                 // `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);
+                    statusTimer = setTimeout(() => resolve("timeout"), STATUS_WAIT_TIMEOUT_MS);
                 });
                 try {
-                    await Promise.race([statusReceived, statusTimeout]);
+                    const outcome = await Promise.race([statusReceived, statusTimeout]);
+                    log(outcome === "timeout"
+                        ? `no reply from the label within ${STATUS_WAIT_TIMEOUT_MS}ms - assuming it painted`
+                        : "label reported the paint complete");
                 }
                 finally {
                     clearTimeout(statusTimer);

package/dist/repaintScheduler.js

@@ -25,6 +25,13 @@ const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
 /** Pause between paint attempts - see `withRetries`' `delayMs`. */
 const PAINT_RETRY_DELAY_MS = 5000;
+/**
+ * Last-resort limit on one paint attempt, on top of its connect timeout - so an attempt stuck on
+ * anything, anywhere, still fails and gets retried instead of blocking this label (and, via
+ * `exclusiveBleManagerAccess`, every other label) forever. Longer than every inner limit it backs up,
+ * the longest being the 5-minute GATT session watchdog in `bleBackend.ts`.
+ */
+const PAINT_ATTEMPT_BACKSTOP_MS = 7 * 60000;
 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
@@ -358,7 +365,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     const paintWithRetries = () => (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
         app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
         const startedAt = Date.now();
-        await driver.paint(bitmap, {
+        const paint = driver.paint(bitmap, {
             address,
             pid: target.pid,
             aesKey: device.advanced?.aesKey,
@@ -368,7 +375,9 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             compress: device.advanced?.compress,
             compressionFormat: device.advanced?.compressionFormat,
             gattBackend,
+            log: (message) => app.debug(`${label}: ${message}`),
         });
+        await (0, bleDiscovery_1.withDeadline)(paint, connectTimeoutMs + PAINT_ATTEMPT_BACKSTOP_MS, `paint attempt ${attempt}/${attempts}`);
         paintDurationMs = Date.now() - startedAt;
     }, {
         delayMs: PAINT_RETRY_DELAY_MS,

package/docs/bluetooth.md

@@ -2,11 +2,21 @@
 
 Advice for getting a reliable Bluetooth Low Energy (BLE) connection between the SignalK server and your labels.
 
-Most of this applies to direct BlueZ mode only. If the "Use the SignalK BLE Manager API" setting is enabled, the adapter and its lifecycle are managed by the SignalK server, under its own Bluetooth admin settings, once for every BLE-consuming plugin.
+Bluetooth can be used in of three ways by a plugin:
+
+- Direct access to dongle (usually `hci0` device). Not recommended
+- Access via `bluez` and `dbus` services. Better but not ideal
+- Using the BLE Manager added to SignalK in 2026. Recommended with caveats.
+  - "Use the SignalK BLE Manager API" setting is enabled, the adapter and its lifecycle are managed by the SignalK server, under its own Bluetooth admin settings, once for every BLE-consuming plugin.
+  - Under the hood, this uses `bluez` and `dbus` however manages them so that plugins are controlled in how they can impact each other
+  - It also has a very useful GUI for seeing all scanned devices, and all GATT claims (GATT being the protocol for directly connecting to BLE devices).
+  - This is still new and settling down, so not yet the default for this plugin
+
+The advice here is general to Bluetooth on Linux, whichever way its being used.
 
 ## Choosing a Bluetooth Adapter
 
-Only needed in direct BlueZ mode - in BLE Manager mode the adapter is whatever the SignalK server's own Bluetooth settings provide.
+First step is having a Bluetooth Low Energy (BLE) compatible bluetooth adapter available.
 
 - Bluetooth adapters for Linux can be tricky
 - TP-Link UB400 and Asus USB-BT500 are two well-known and available ones, though the ASUS USB-BT500 one can have problems with some Pi type boards (see [Adapter stops responding](#adapter-stops-responding-no-gpio-to-reset))
@@ -18,10 +28,14 @@ Only needed in direct BlueZ mode - in BLE Manager mode the adapter is whatever t
 > - Don't worry about the very latest Bluetooth versions, 4.0 is minimum for BLE, 5.0 is nice
 > - Home Assistant is massively more popular than SignalK, and often also run on Raspberry Pi and similar, so good source of advice
 
+SignalK BLE Manager also supports BLE Gateways, which could be an MQTT topic or an ESP-32 device. The [espos-ble-gateway](https://github.com/dirkwa/espos-ble-gateway) can be used with a cheap ESP32 device (see the list of supported hardware), which allows positioning of the gateway closer to devices, or having multiple gateways on a big boat.
+
 ## Weak Signal
 
 If the label is too far from the SignalK server's adapter, try a BLE proxy device - ESP32 is popular for this - or, with the BLE Manager API, a remote BLE gateway.
 
+If your dongle is plugged into a USB3 port (usually blue-highlighted), then there's a good chance the [infamous USB3 interference on the 2.4Ghz spectrum](https://www.usb.org/sites/default/files/327216.pdf) is impacting your adapter. Switch to a USB2 port if you have one, or better, use a USB extension cable to position the dongle far away.
+
 ## Bluetooth Plugins Impacting Each Other
 
 Bluetooth plugins can kick off scanning, and otherwise interfere with each other. Worst case is when plugins attempt to connect directly to Bluetooth adapters. Better is when they connect using `bluez` and `dbus` Linux components, and best of all when they use the SignalK BLE Manager added in 2026.
@@ -84,7 +98,11 @@ Bluetooth: hci0: command 0x2042 tx timeout
 Bluetooth: hci0: Opcode 0x2042 failed: -110
 ```
 
-This happens when USB autosuspend cycles the dongle in and out of low-power suspend while idle. When bluetoothd sends an HCI command while the device is suspended or mid-resume, it never gets answered — adapters like the popular ASUS USB-500 lack a GPIO to allow reset and its stuck, and spams logs.
+Adapters like the popular ASUS USB-500 lack a GPIO to allow reset when suspended and it gets stuck, spamming the logs. See [Adapter Goes to Sleep](#adapter-goes-to-sleep) for stopping the auto-suspend happening.
+
+## Adapter Goes to Sleep
+
+This happens when USB autosuspend cycles the dongle in and out of low-power suspend while idle. When bluetoothd sends an HCI command while the device is suspended or mid-resume, it never gets answered
 
 ### Example udev rule fix
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.0-beta13",
+  "version": "1.3.0-beta14",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",