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

package/dist/config.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RENDER_FALLBACK_TEMPLATE_NAME = exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
+exports.migrateConfig = migrateConfig;
 exports.defaultConfig = defaultConfig;
 exports.readCurrentConfig = readCurrentConfig;
-exports.healNestedConfig = healNestedConfig;
+exports.healStoredConfig = healStoredConfig;
 exports.resolveTemplatesDir = resolveTemplatesDir;
 exports.parseDevice = parseDevice;
 exports.resolveTemplatePath = resolveTemplatePath;
@@ -23,6 +24,49 @@ const resolveApiUrl_1 = require("./resolveApiUrl");
  * an on-demand scan itself if nothing's been discovered yet.
  */
 exports.ALL_DEVICES = "ALL";
+/**
+ * Every `AdvancedDeviceSettings` key - these all used to sit directly on `DeviceConfig`, so a config
+ * saved before they were grouped still has them there. See `migrateDeviceConfig`.
+ */
+const ADVANCED_DEVICE_KEYS = [
+    "compress",
+    "mirror",
+    "compressionFormat",
+    "forceRepaint",
+    "aesKey",
+    "paintConnectTimeoutSeconds",
+    "paintRetries",
+];
+/**
+ * Moves any `AdvancedDeviceSettings` key found at the top level of a device entry (the pre-grouping
+ * layout) into its `advanced` object, reporting whether anything moved. A value already under
+ * `advanced` wins over a legacy top-level one - it can only have got there from the grouped form, so
+ * it's the newer of the two.
+ */
+function migrateDeviceConfig(raw) {
+    const legacy = {};
+    const rest = { ...raw };
+    for (const key of ADVANCED_DEVICE_KEYS) {
+        if (key in rest) {
+            legacy[key] = rest[key];
+            delete rest[key];
+        }
+    }
+    if (Object.keys(legacy).length === 0) {
+        return { device: raw, migrated: false };
+    }
+    return { device: { ...rest, advanced: { ...legacy, ...raw.advanced } }, migrated: true };
+}
+/** Applies `migrateDeviceConfig` to every device entry - see `healStoredConfig` for persisting the result. */
+function migrateConfig(config) {
+    if (!Array.isArray(config.devices)) {
+        return { config, migrated: false };
+    }
+    const results = config.devices.map(migrateDeviceConfig);
+    return results.some((result) => result.migrated)
+        ? { config: { ...config, devices: results.map((result) => result.device) }, migrated: true }
+        : { config, migrated: false };
+}
 /**
  * The package's own bundled `templates/` directory (ships alongside `dist/`, see
  * package.json's `files`) - templates here are always available, but a same-named template in the
@@ -108,27 +152,33 @@ function pickKnownKeys(raw) {
 }
 function readCurrentConfig(app) {
     const { unwrapped } = unwrapNestedConfiguration(app.readPluginOptions());
-    return pickKnownKeys(unwrapped);
+    return migrateConfig(pickKnownKeys(unwrapped)).config;
 }
 /**
- * Actively rewrites the on-disk file once it's nested (see `readCurrentConfig`'s doc comment) -
- * `readCurrentConfig` alone only self-heals in memory for callers that go through it, but the admin
- * UI's own config-editing form round-trips whatever raw JSON it was handed verbatim, including a
- * stray nested `configuration` key it never touches (no schema field maps to it) - so left alone,
- * every future save from the UI keeps re-persisting that dead weight forever (see
- * `support/signalk-einklabel-plugin.json`). Called once at plugin start, which - unlike
- * `clearForceRepaint` - isn't gated on any device having `forceRepaint` set, so a nested file gets
- * flattened even if nothing ever triggers that path.
+ * Actively rewrites the on-disk file when it's in an outdated shape - `readCurrentConfig` alone only
+ * fixes things up in memory for callers that go through it, but the admin UI's config form
+ * round-trips whatever raw JSON it was handed verbatim. Two shapes are healed:
+ *
+ * - A nested file (see `readCurrentConfig`'s doc comment): left alone, the UI keeps re-persisting a
+ *   stray nested `configuration` key it never touches (no schema field maps to it) forever (see
+ *   `support/signalk-einklabel-plugin.json`).
+ * - Advanced device settings saved before they were grouped under `advanced` (see
+ *   `migrateDeviceConfig`): left alone, the UI would show that group empty, even though the plugin
+ *   itself still honours the old values.
+ *
+ * Called once at plugin start, which - unlike `clearForceRepaint` - isn't gated on any device having
+ * `forceRepaint` set, so an outdated file gets fixed even if nothing ever triggers that path.
  */
-function healNestedConfig(app) {
+function healStoredConfig(app) {
     const { unwrapped, wasNested } = unwrapNestedConfiguration(app.readPluginOptions());
-    if (!wasNested)
+    const { config, migrated } = migrateConfig(pickKnownKeys(unwrapped));
+    if (!wasNested && !migrated)
         return;
-    app.savePluginOptions(pickKnownKeys(unwrapped), (err) => {
+    app.savePluginOptions(config, (err) => {
         if (err)
-            app.debug(`failed to clean up legacy nested plugin config: ${err.message}`);
+            app.debug(`failed to update the stored plugin config: ${err.message}`);
         else
-            app.debug("cleaned up a legacy nested plugin config file on disk");
+            app.debug(`updated the stored plugin config (${[wasNested && "flattened nesting", migrated && "grouped advanced device settings"].filter(Boolean).join(", ")})`);
     });
 }
 /**
@@ -298,9 +348,34 @@ function resolveTemplatePath(templatesDir, templateName, target) {
     const localPath = (0, path_1.join)(templatesDir, templateName);
     return (0, fs_1.existsSync)(localPath) ? localPath : (0, path_1.join)(exports.BUNDLED_TEMPLATES_DIR, templateName);
 }
-/** JSON Schema forbids an empty `enum` array, so only attach one when there's at least one option - otherwise the whole config schema fails validation. */
+/**
+ * Restricts a string field to `values`, shown as `names` where given - as `oneOf` with `const`/`title`,
+ * the form RJSF 5 (the admin UI's form library) supports going forward, rather than the deprecated
+ * `enumNames`. JSON Schema forbids an empty `enum`/`oneOf` array, so neither is attached without at
+ * least one option - otherwise the whole config schema fails validation.
+ */
 function withEnum(schema, values, names) {
-    return values.length > 0 ? { ...schema, enum: values, ...(names ? { enumNames: names } : {}) } : schema;
+    if (values.length === 0)
+        return schema;
+    return names ? { ...schema, oneOf: values.map((value, i) => ({ const: value, title: names[i] ?? value })) } : { ...schema, enum: values };
+}
+/**
+ * An enum-like string field whose options show explanatory labels rather than their raw stored values
+ * - `oneOf` with `const`/`title`, which RJSF 5 (the admin UI's form library) renders as each option's
+ * label while still saving the bare value, so existing configs are unaffected.
+ *
+ * Each label is prefixed with an en space: the admin UI renders RJSF's default-theme radio markup under
+ * Bootstrap 5, which has no styling for it, so the label otherwise butts straight up against its
+ * button - and a plugin can't ship its own CSS. An en space, unlike a plain one, isn't collapsed away
+ * by HTML whitespace handling.
+ */
+function choiceField(title, options, extra = {}) {
+    return {
+        type: "string",
+        title,
+        ...extra,
+        oneOf: options.map(([value, label]) => ({ const: value, title: `\u2002${label}` })),
+    };
 }
 function configSchema(app, discovered = []) {
     const defaults = defaultConfig();
@@ -309,6 +384,18 @@ function configSchema(app, discovered = []) {
     return {
         type: "object",
         properties: {
+            ...(app.bleApi
+                ? {
+                    useBleApi: {
+                        type: "boolean",
+                        title: "Use the SignalK BLE Manager API",
+                        description: "Route Bluetooth access through SignalK server's BLE Manager API (server >= 2.32.0) instead of connecting to " +
+                            "BlueZ directly, so this plugin shares the adapter with other BLE plugins instead of contending for it. Requires " +
+                            "the server to have a local Bluetooth adapter or BLE gateway available (Server → Settings → Bluetooth).",
+                        default: defaults.useBleApi,
+                    },
+                }
+                : {}),
             templatesDir: {
                 type: "string",
                 title: "Templates directory",
@@ -321,7 +408,8 @@ function configSchema(app, discovered = []) {
                 type: "boolean",
                 title: "Scan for devices on plugin start",
                 description: 'Runs a short BLE scan so discovered devices show up in a device\'s "Device" picker below. ' +
-                    'Not needed if every device uses "All discovered devices" - that scans on demand instead.',
+                    'Not needed if every device uses "All discovered devices" (that scans on demand instead), or if ' +
+                    '"Use BLE Manager" below is on (that discovers continuously in the background instead of needing a scan).',
                 default: defaults.scanOnStart,
             },
             scanDurationSeconds: {
@@ -331,29 +419,19 @@ function configSchema(app, discovered = []) {
                 minimum: 1,
                 default: defaults.scanDurationSeconds,
             },
-            ...(app.bleApi
-                ? {
-                    useBleApi: {
-                        type: "boolean",
-                        title: "Use the SignalK BLE Manager API",
-                        description: "Route Bluetooth access through SignalK server's BLE Manager API (server >= 2.32.0) instead of connecting to " +
-                            "BlueZ directly, so this plugin shares the adapter with other BLE plugins instead of contending for it. Requires " +
-                            "the server to have a local Bluetooth adapter or BLE gateway available (Server → Settings → Bluetooth).",
-                        default: defaults.useBleApi,
-                    },
-                }
-                : {}),
             paintConnectTimeoutSeconds: {
                 type: "number",
                 title: "Paint connect timeout (seconds)",
-                description: "How long to wait for a device to accept a BLE connection before giving up on a repaint attempt.",
+                description: "How long to wait for a device to accept a BLE connection before giving up on a repaint attempt. " +
+                    "The default for every device - each device can override it in its own settings below.",
                 minimum: 1,
                 default: defaults.paintConnectTimeoutSeconds,
             },
             paintRetries: {
                 type: "number",
                 title: "Paint retries",
-                description: "How many times to attempt a repaint (including the first try) before giving up and reporting failure.",
+                description: "How many times to attempt a repaint (including the first try) before giving up and reporting failure. " +
+                    "The default for every device - each device can override it in its own settings below.",
                 minimum: 1,
                 default: defaults.paintRetries,
             },
@@ -394,11 +472,10 @@ function configSchema(app, discovered = []) {
                                 'in poor light" - available to any template as source=einklabel,path=description or source=label,path=description.',
                         },
                         templateName: withEnum({ type: "string", title: "Template" }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
-                        repaintTrigger: {
-                            type: "string",
-                            title: "Repaint trigger",
-                            enum: ["subscription", "interval"],
-                        },
+                        repaintTrigger: choiceField("Repaint trigger", [
+                            ["subscription", "When a SignalK path changes"],
+                            ["interval", "On a timed schedule"],
+                        ]),
                         triggerPath: {
                             type: "string",
                             title: "Trigger SignalK path (if repaint trigger is subscription)",
@@ -415,22 +492,58 @@ function configSchema(app, discovered = []) {
                             maximum: 59,
                             default: 0,
                         },
-                        aesKey: {
-                            type: "string",
-                            title: "BLE AES key (vendor-specific; leave blank to use a default key)",
-                        },
-                        forceRepaint: {
-                            type: "boolean",
-                            title: "Force repaint",
-                            description: "Repaint even if the data is unchanged - clears itself automatically once that repaint completes",
-                            default: false,
-                        },
-                        reframe: {
-                            type: "string",
-                            title: "If the render doesn't match the panel size",
-                            description: "Crop: place at the top-left, truncating anything too big or leaving the rest blank if too small. Scale: stretch to fit exactly (may distort). Fixed: fail the repaint instead of showing an off-size image.",
-                            enum: ["crop", "scale", "fixed"],
-                            default: "crop",
+                        reframe: choiceField("If the render doesn't match the panel size", [
+                            ["crop", "Crop - place at the top-left, cutting off anything too big or leaving the rest blank"],
+                            ["scale", "Scale - stretch to fit exactly (may distort)"],
+                            ["fixed", "Fixed - fail the repaint rather than show an off-size image"],
+                        ], { default: "crop" }),
+                        advanced: {
+                            type: "object",
+                            title: "Advanced settings",
+                            description: "Most labels never need these.",
+                            properties: {
+                                compress: {
+                                    type: "boolean",
+                                    title: 'Compress upload (Zhsunyco, Gicisky 7.5"/10.2")',
+                                    description: "Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating.",
+                                    default: true,
+                                },
+                                mirror: choiceField("Mirror", [
+                                    ["none", "No flip"],
+                                    ["horizontal", "Flip left to right"],
+                                    ["vertical", "Flip top to bottom"],
+                                    ["both", "Rotate 180° - for a label mounted upside down"],
+                                ], { description: "Only needed if the image shows up mirrored or upside down on the label.", default: "none" }),
+                                compressionFormat: choiceField("Wire format (Gicisky, experimental)", [
+                                    ["auto", "Auto - the model's usual format"],
+                                    [
+                                        "chunked",
+                                        'Chunked - send compressed like the 7.5"/10.2" panels, e.g. to speed up a 4.2" BWR (untested on current firmware)',
+                                    ],
+                                ], { description: "Chunked needs Compress upload on. Switch back to Auto if the label stops updating.", default: "auto" }),
+                                forceRepaint: {
+                                    type: "boolean",
+                                    title: "Force repaint",
+                                    description: "Repaint even if the data is unchanged - clears itself automatically once that repaint completes",
+                                    default: false,
+                                },
+                                aesKey: {
+                                    type: "string",
+                                    title: "BLE AES key (vendor-specific; leave blank to use a default key)",
+                                },
+                                paintConnectTimeoutSeconds: {
+                                    type: "number",
+                                    title: "Paint connect timeout for this device (seconds)",
+                                    description: `Leave blank to use the plugin-wide setting (currently ${current.paintConnectTimeoutSeconds}s).`,
+                                    minimum: 1,
+                                },
+                                paintRetries: {
+                                    type: "number",
+                                    title: "Paint retries for this device",
+                                    description: `Leave blank to use the plugin-wide setting (currently ${current.paintRetries}).`,
+                                    minimum: 1,
+                                },
+                            },
                         },
                     },
                 },
@@ -445,6 +558,10 @@ function configUiSchema() {
                 description: { "ui:widget": "textarea" },
                 repaintTrigger: { "ui:widget": "radio" },
                 reframe: { "ui:widget": "radio" },
+                advanced: {
+                    mirror: { "ui:widget": "radio" },
+                    compressionFormat: { "ui:widget": "radio" },
+                },
             },
         },
     };

package/dist/devices/bleBackend.d.ts

@@ -12,10 +12,38 @@ export interface BleBackend {
     connectGatt(address: string, timeoutMs: number): Promise<GattConnection>;
     waitForManufacturerData(address: string, manufacturerId: number, timeoutMs: number): Promise<Buffer | undefined>;
 }
+/**
+ * Wraps a connected `GattConnection` so the session as a whole - not just the connect step - can't
+ * hang forever. Starts a single timer when the connection opens; if `disconnect()` hasn't been
+ * called (i.e. the caller's `paint()` hasn't finished, successfully or not) by the time it fires,
+ * treats the session as stuck: calls `forceClose` (which must tear down the connection and, for a
+ * shared backend, release any claim on it) and fails every call still outstanding or made afterwards.
+ * `Promise.race`ing each call against that same failure - rather than just refusing new calls once
+ * killed - is what actually unblocks a caller `await`ing a hung `write()`/`discoverServices()`:
+ * forcing the underlying connection closed doesn't guarantee the hung call's own promise ever
+ * settles, so the caller needs a second, independent way to move on.
+ */
+export declare function withSessionWatchdog(conn: GattConnection, timeoutMs: number, forceClose: () => Promise<void>): GattConnection;
 export declare function nodeBleBackend(): BleBackend;
+/**
+ * Waits for the BLE Manager to know about `address` before a GATT connect is attempted against it -
+ * mirrors `getOrDiscoverDevice` in `bleDiscovery.ts`, which gives `nodeBleBackend` the same guarantee
+ * against BlueZ directly. Without this, a specifically-addressed device that the manager hasn't seen
+ * yet (e.g. this plugin's own `scanOnStart` is off and no other BLE plugin happens to be scanning)
+ * would sit on `bleApi.connectGATT()` until that call's own `timeoutMs` gives up, rather than the
+ * plugin quietly rediscovering it the way the direct-BlueZ backend already does.
+ */
+export declare function ensureDeviceVisible(bleApi: BLEApi, pluginId: string, address: string, timeoutMs: number): Promise<void>;
+/**
+ * Runs `fn` only once every earlier caller has finished, so paints to different devices never hold
+ * BLE Manager GATT slots at the same time. The server's local provider defaults to just a couple of
+ * slots shared with every other BLE plugin (e.g. Bluetti), so two concurrent connects can leave the
+ * second with none free - which the server reports as the misleading "No provider with GATT support
+ * can see <mac>".
+ */
+export declare function exclusiveBleManagerAccess<T>(fn: () => Promise<T>): Promise<T>;
 /**
  * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
- * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs` and disconnects in the
- * background if it eventually resolves after the caller has already given up.
+ * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.
  */
 export declare function bleApiBackend(bleApi: BLEApi, pluginId: string): BleBackend;

package/dist/devices/bleBackend.js

@@ -1,10 +1,82 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSessionWatchdog = withSessionWatchdog;
 exports.nodeBleBackend = nodeBleBackend;
+exports.ensureDeviceVisible = ensureDeviceVisible;
+exports.exclusiveBleManagerAccess = exclusiveBleManagerAccess;
 exports.bleApiBackend = bleApiBackend;
+const pluginVersion_1 = require("../pluginVersion");
 const bleDiscovery_1 = require("./bleDiscovery");
 /** How long to wait for BlueZ to have (or acquire) a `Device` object for the target address before giving up - a separate budget from the connect step itself, matching both drivers' previous hardcoded constant. */
 const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
+/**
+ * Bounds the whole post-connect GATT session (service discovery, every read/write/notification a
+ * driver's `paint()` makes until it calls `disconnect()`), not just the connect step above - unlike
+ * `connectWithTimeout`/`bleApiBackend`'s connect race, neither backend's underlying `write()` or
+ * `discoverServices()` has any timeout of its own, so a hang there (plausible against a flaky real
+ * device) would otherwise sit forever with the connection, and any BLE Manager GATT claim, held open
+ * - see `withSessionWatchdog`. Generous relative to any single driver operation's own timeout (e.g.
+ * gicisky's 15s per-chunk ack) since it has to cover a whole multi-chunk image transfer, not one step
+ * of it; it's a last-resort backstop, not a normal-path budget.
+ */
+const GATT_SESSION_WATCHDOG_MS = 5 * 60000;
+/**
+ * Wraps a connected `GattConnection` so the session as a whole - not just the connect step - can't
+ * hang forever. Starts a single timer when the connection opens; if `disconnect()` hasn't been
+ * called (i.e. the caller's `paint()` hasn't finished, successfully or not) by the time it fires,
+ * treats the session as stuck: calls `forceClose` (which must tear down the connection and, for a
+ * shared backend, release any claim on it) and fails every call still outstanding or made afterwards.
+ * `Promise.race`ing each call against that same failure - rather than just refusing new calls once
+ * killed - is what actually unblocks a caller `await`ing a hung `write()`/`discoverServices()`:
+ * forcing the underlying connection closed doesn't guarantee the hung call's own promise ever
+ * settles, so the caller needs a second, independent way to move on.
+ */
+function withSessionWatchdog(conn, timeoutMs, forceClose) {
+    let killedError;
+    let resolveKilled;
+    const killed = new Promise((resolve) => {
+        resolveKilled = resolve;
+    });
+    let settled = false;
+    // `unref()` so this backstop timer never itself keeps the process alive (e.g. the CLI's `paint`
+    // command exiting naturally once its work is done) - it only ever needs to fire while something
+    // else is already keeping the event loop running anyway.
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        killedError = new Error(`GATT session watchdog fired after ${timeoutMs}ms with no completion - forcing disconnect`);
+        console.error(`${pluginVersion_1.PLUGIN_NAME}: ${killedError.message}`);
+        resolveKilled(killedError);
+        void forceClose().catch(() => { });
+    }, timeoutMs).unref();
+    function guard(op) {
+        if (killedError)
+            return Promise.reject(killedError);
+        const result = op();
+        result.catch(() => { }); // observed here too, so losing the race below never surfaces as an unhandled rejection
+        return Promise.race([result, killed.then((err) => Promise.reject(err))]);
+    }
+    return {
+        read: (serviceUuid, charUuid) => guard(() => conn.read(serviceUuid, charUuid)),
+        write: (serviceUuid, charUuid, data, withResponse) => guard(() => conn.write(serviceUuid, charUuid, data, withResponse)),
+        startNotifications: (serviceUuid, charUuid, callback) => guard(() => conn.startNotifications(serviceUuid, charUuid, callback)),
+        stopNotifications: (serviceUuid, charUuid) => guard(() => conn.stopNotifications(serviceUuid, charUuid)),
+        discoverServices: () => guard(() => conn.discoverServices()),
+        onDisconnect: conn.onDisconnect.bind(conn),
+        get connected() {
+            return conn.connected;
+        },
+        async disconnect() {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killedError)
+                return; // already forced closed by the watchdog above
+            await conn.disconnect();
+        },
+    };
+}
 function nodeBleBackend() {
     return {
         async connectGatt(address, timeoutMs) {
@@ -14,7 +86,14 @@ function nodeBleBackend() {
                 const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, address, DEVICE_DISCOVERY_TIMEOUT_MS);
                 await (0, bleDiscovery_1.connectWithTimeout)(device, timeoutMs);
                 const conn = (0, bleDiscovery_1.openNodeBleGattConnection)(device);
-                return {
+                let destroyed = false;
+                const destroyOnce = () => {
+                    if (destroyed)
+                        return;
+                    destroyed = true;
+                    destroy();
+                };
+                const gatt = {
                     read: conn.read.bind(conn),
                     write: conn.write.bind(conn),
                     startNotifications: conn.startNotifications.bind(conn),
@@ -25,10 +104,22 @@ function nodeBleBackend() {
                         return conn.connected;
                     },
                     async disconnect() {
-                        await conn.disconnect();
-                        destroy();
+                        try {
+                            await conn.disconnect();
+                        }
+                        finally {
+                            destroyOnce();
+                        }
                     },
                 };
+                return withSessionWatchdog(gatt, GATT_SESSION_WATCHDOG_MS, async () => {
+                    // `device.disconnect()` can hang for the same underlying reason the operations
+                    // `withSessionWatchdog` already guards can (see its doc comment) - race it briefly rather
+                    // than awaiting it unbounded here too, but tear down the D-Bus connection either way so
+                    // those resources don't leak even if BlueZ's disconnect itself never completes.
+                    await Promise.race([gatt.disconnect(), (0, bleDiscovery_1.sleep)(5000)]);
+                    destroyOnce();
+                });
             }
             catch (err) {
                 destroy();
@@ -48,10 +139,53 @@ function nodeBleBackend() {
         },
     };
 }
+/**
+ * Waits for the BLE Manager to know about `address` before a GATT connect is attempted against it -
+ * mirrors `getOrDiscoverDevice` in `bleDiscovery.ts`, which gives `nodeBleBackend` the same guarantee
+ * against BlueZ directly. Without this, a specifically-addressed device that the manager hasn't seen
+ * yet (e.g. this plugin's own `scanOnStart` is off and no other BLE plugin happens to be scanning)
+ * would sit on `bleApi.connectGATT()` until that call's own `timeoutMs` gives up, rather than the
+ * plugin quietly rediscovering it the way the direct-BlueZ backend already does.
+ */
+async function ensureDeviceVisible(bleApi, pluginId, address, timeoutMs) {
+    const known = await bleApi.getDevice(address).catch(() => null);
+    if (known)
+        return;
+    const seen = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            unsubscribe();
+            resolve(false);
+        }, timeoutMs);
+        const unsubscribe = bleApi.onAdvertisement(pluginId, (adv) => {
+            if (adv.mac !== address)
+                return;
+            clearTimeout(timer);
+            unsubscribe();
+            resolve(true);
+        });
+    });
+    if (!seen) {
+        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 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();
+/**
+ * Runs `fn` only once every earlier caller has finished, so paints to different devices never hold
+ * BLE Manager GATT slots at the same time. The server's local provider defaults to just a couple of
+ * slots shared with every other BLE plugin (e.g. Bluetti), so two concurrent connects can leave the
+ * second with none free - which the server reports as the misleading "No provider with GATT support
+ * can see <mac>".
+ */
+function exclusiveBleManagerAccess(fn) {
+    const run = bleManagerQueue.then(fn, fn);
+    bleManagerQueue = run.catch(() => { });
+    return run;
+}
 /**
  * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
- * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs` and disconnects in the
- * background if it eventually resolves after the caller has already given up.
+ * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.
  */
 function bleApiBackend(bleApi, pluginId) {
     return {
@@ -61,20 +195,58 @@ function bleApiBackend(bleApi, pluginId) {
             // "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 ensureDeviceVisible(bleApi, pluginId, address, DEVICE_DISCOVERY_TIMEOUT_MS);
             const connecting = bleApi.connectGATT(address, pluginId);
             let timedOut = false;
             const conn = await Promise.race([connecting, (0, bleDiscovery_1.sleep)(timeoutMs).then(() => void (timedOut = true))]);
             if (timedOut || !conn) {
-                connecting.then((c) => c.disconnect()).catch(() => { });
+                // The server registers the claim as soon as `connectGATT()` is called, not once it succeeds -
+                // giving up here without releasing it would leave the claim (and, once/if the connect attempt
+                // does eventually land server-side, a live connection) orphaned indefinitely, since this
+                // plugin never gets a handle back to disconnect it itself. `releaseGATTDevice` tears down
+                // whatever the claim currently is, connected or still connecting, regardless of how the
+                // original `connectGATT()` promise eventually settles - disconnecting it too if it does still
+                // resolve afterwards, harmlessly, since a connection the server already released is a no-op to
+                // 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(() => { });
+                // ...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".
+                // Give that connect a bounded chance to settle first, so the retry gets a clean slate.
+                const late = await Promise.race([
+                    connecting.catch(() => undefined),
+                    (0, bleDiscovery_1.sleep)(Math.min(timeoutMs, CONNECT_SETTLE_GRACE_MS)).then(() => undefined),
+                ]);
+                if (late) {
+                    await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), late.disconnect()]);
+                }
+                else {
+                    void connecting.then((c) => c.disconnect()).catch(() => { });
+                }
                 throw new Error(`connecting to device timed out after ${timeoutMs}ms`);
             }
-            return conn;
+            return withSessionWatchdog(conn, GATT_SESSION_WATCHDOG_MS, async () => {
+                // 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()]);
+            });
         },
         async waitForManufacturerData(address, manufacturerId, timeoutMs) {
             // Unlike node-ble's `device.getManufacturerData()`, there's no cached-instant-read path here -
             // `BLEDeviceInfo` (from `getDevices()`/`getDevice()`) carries mac/name/rssi/seenBy but not
             // manufacturer data (see `BLEDeviceInfoSchema` in `@signalk/server-api`'s `ble-schemas.ts`) -
             // only the streamed `BLEAdvertisement` does. So this always actively waits on the stream.
+            //
+            // Same defensive release as `connectGatt`, and just as necessary here: a device the BLE Manager
+            // still thinks *we* hold a GATT claim on (e.g. from a crash/reload mid-paint, before this call
+            // ever reaches `connectGatt` below) stops advertising while claimed - which would otherwise wedge
+            // 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(() => { });
             return new Promise((resolve) => {
                 const timer = setTimeout(() => {
                     unsubscribe();

package/dist/devices/bleDiscovery.d.ts

@@ -34,9 +34,16 @@ export declare function forEachAdvertisedDevice(adapter: Adapter, fn: (advertise
 /**
  * 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.
+ * doesn't fail a whole repaint after a single bad attempt. `delayMs` pauses between attempts, giving
+ * the adapter (and any BLE Manager claim the failed attempt held) a moment to settle rather than
+ * hitting the device again in the same tick. `onError` sees every failed attempt's error, not just the
+ * last one that's eventually thrown - an early attempt's error is often the real cause, with later
+ * ones just fallout from it.
  */
-export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>): Promise<T>;
+export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>, { delayMs, onError }?: {
+    delayMs?: number;
+    onError?: (err: unknown, attempt: number) => void;
+}): 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

package/dist/devices/bleDiscovery.js

@@ -68,16 +68,25 @@ async function forEachAdvertisedDevice(adapter, fn) {
 /**
  * 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.
+ * doesn't fail a whole repaint after a single bad attempt. `delayMs` pauses between attempts, giving
+ * the adapter (and any BLE Manager claim the failed attempt held) a moment to settle rather than
+ * hitting the device again in the same tick. `onError` sees every failed attempt's error, not just the
+ * last one that's eventually thrown - an early attempt's error is often the real cause, with later
+ * ones just fallout from it.
  */
-async function withRetries(attempts, fn) {
+async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
+    const total = Math.max(1, attempts);
     let lastErr;
-    for (let attempt = 1; attempt <= Math.max(1, attempts); attempt++) {
+    for (let attempt = 1; attempt <= total; attempt++) {
         try {
             return await fn(attempt);
         }
         catch (err) {
             lastErr = err;
+            onError?.(err, attempt);
+            if (attempt < total && delayMs > 0) {
+                await sleep(delayMs);
+            }
         }
     }
     throw lastErr;