@rhizomatics/signalk-einklabel-plugin 1.3.0-beta9 → 1.3.1

package/dist/repaintScheduler.d.ts

@@ -1,7 +1,18 @@
 import { ServerAPI } from "@signalk/server-api";
 import { PluginConfig } from "./config";
+/**
+ * How long `stop()` waits for a paint already in progress before resolving anyway. Long enough for a
+ * normal transfer to finish (so a config save mid-paint doesn't have the next `start()` connect while
+ * the old BLE session is still open), short enough not to hold up server shutdown on a label that's
+ * stuck; such a paint is still ended by its own connect timeout and `PAINT_ATTEMPT_BACKSTOP_MS`.
+ */
+export declare const STOP_DRAIN_TIMEOUT_MS = 30000;
 export interface RepaintScheduler {
-    stop(): void;
+    /**
+     * Stops every trigger, lets no new paint or retry start, and resolves once any paint already in
+     * progress finishes - or after `STOP_DRAIN_TIMEOUT_MS`, whichever comes first.
+     */
+    stop(): Promise<void>;
 }
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own
@@ -13,4 +24,21 @@ export interface RepaintScheduler {
  * rather than waiting up to `intervalHours` for the next one).
  */
 export declare function mostRecentScheduledSlot(now: Date, intervalHours: number, intervalMinute: number): Date;
+/**
+ * Wraps `run` so only one call per key is in progress at a time. A call made while that key is busy
+ * is folded into a single follow-up (with the latest arguments), run once the current one finishes -
+ * but only if it succeeded (`run` resolved `true`). For repaints: newer data still gets shown promptly,
+ * but a label that's failing isn't hammered with a fresh round of retries straight after the last
+ * one gave up - the next scheduled trigger tries again instead.
+ *
+ * `close()` makes every later call a no-op and drops pending follow-ups; `idle()` resolves once no
+ * `run` is in progress. Together they let the scheduler's `stop()` wait for a paint already under way
+ * without starting another.
+ */
+export interface OneAtATimePerKey<T> {
+    (arg: T): Promise<void>;
+    close(): void;
+    idle(): Promise<void>;
+}
+export declare function oneAtATimePerKey<T>(keyOf: (arg: T) => string, run: (arg: T) => Promise<boolean>, onBusy?: (arg: T) => void): OneAtATimePerKey<T>;
 export declare function startRepaintScheduler(app: ServerAPI, config: PluginConfig): RepaintScheduler;

package/dist/repaintScheduler.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOP_DRAIN_TIMEOUT_MS = void 0;
 exports.mostRecentScheduledSlot = mostRecentScheduledSlot;
+exports.oneAtATimePerKey = oneAtATimePerKey;
 exports.startRepaintScheduler = startRepaintScheduler;
 const crypto_1 = require("crypto");
 const path_1 = require("path");
@@ -25,6 +27,20 @@ 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;
+/**
+ * How long `stop()` waits for a paint already in progress before resolving anyway. Long enough for a
+ * normal transfer to finish (so a config save mid-paint doesn't have the next `start()` connect while
+ * the old BLE session is still open), short enough not to hold up server shutdown on a label that's
+ * stuck; such a paint is still ended by its own connect timeout and `PAINT_ATTEMPT_BACKSTOP_MS`.
+ */
+exports.STOP_DRAIN_TIMEOUT_MS = 30000;
 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
@@ -175,7 +191,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}`);
@@ -240,7 +256,7 @@ async function resolveTargets(app, config, device) {
  * prompt showing "gentle breezes" through an actual storm), and not persisting a hash means the very
  * next scheduled tick retries for real rather than being suppressed by dedup.
  */
-async function considerRepaint(app, config, device, target, state, getApiUrl) {
+async function considerRepaint(app, config, device, target, state, getApiUrl, isStopping = () => false) {
     const { address, metadata, driver } = target;
     const label = `"${device.friendlyName}" [${address}]`;
     if (!device.templateName) {
@@ -260,6 +276,23 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     let dataHash = "";
     let paintDurationMs = 0;
     let repaintReason = "render failed";
+    // Built up front, outside the try below, so the fallback warning render gets it too - it's all local
+    // facts (no network or template involved), so there's nothing here that can fail a render.
+    const rawPosition = (0, unwrapSignalkTree_1.unwrapSignalkTree)(app.getSelfPath("navigation.position"));
+    const position = typeof rawPosition?.latitude === "number" && typeof rawPosition?.longitude === "number"
+        ? { latitude: rawPosition.latitude, longitude: rawPosition.longitude }
+        : undefined;
+    const labelContext = (0, binding_1.buildLabelContext)({
+        // Falls back to the driver's own internal vendor key (e.g. "zhsunyco") when a device model has no
+        // explicit `manufacturer` of its own - see `DeviceMetadata.manufacturer`'s doc comment.
+        manufacturer: metadata.manufacturer ?? target.vendor,
+        label: metadata.label,
+        width,
+        height,
+        colours: metadata.colours,
+        description: device.description,
+        position,
+    });
     try {
         const apiUrl = await getApiUrl().catch((err) => {
             app.debug(`${label}: ${err.message}`);
@@ -281,21 +314,6 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             bindings = (0, binding_1.findBindings)((0, fs_1.readFileSync)(templatePath, "utf-8"));
         }
         const rawContext = await assembleRawContext(app, apiUrl, bindings);
-        const rawPosition = (0, unwrapSignalkTree_1.unwrapSignalkTree)(app.getSelfPath("navigation.position"));
-        const position = typeof rawPosition?.latitude === "number" && typeof rawPosition?.longitude === "number"
-            ? { latitude: rawPosition.latitude, longitude: rawPosition.longitude }
-            : undefined;
-        const labelContext = (0, binding_1.buildLabelContext)({
-            // Falls back to the driver's own internal vendor key (e.g. "zhsunyco") when a device model has no
-            // explicit `manufacturer` of its own - see `DeviceMetadata.manufacturer`'s doc comment.
-            manufacturer: metadata.manufacturer ?? target.vendor,
-            label: metadata.label,
-            width,
-            height,
-            colours: metadata.colours,
-            description: device.description,
-            position,
-        });
         // Hashed before `meta` is merged in below, deliberately, so a template merely *displaying* the
         // repaint timestamp doesn't perpetually invalidate its own dedup and force a repaint every check. A
         // full paint flashes the whole panel several times, and there's no confirmed partial-refresh path
@@ -309,7 +327,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;
         }
@@ -320,14 +338,24 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
                 repainted: new Date().toISOString(),
                 local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)(rawContext),
                 plugin_version: pluginVersion_1.PLUGIN_VERSION,
+                // Undocumented legacy alias of `label.description` - kept so templates already using it keep working.
                 description: device.description ?? "",
             },
         };
+        const providerRequest = { templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours };
+        if (provider?.describeContent) {
+            try {
+                app.debug(`${label}: provider content:\n${provider.describeContent(providerRequest)}`);
+            }
+            catch (err) {
+                app.debug(`${label}: describeContent failed (${err.message})`);
+            }
+        }
         bitmap = provider
-            ? await provider.render({ templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours })
+            ? await provider.render(providerRequest)
             : 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"
@@ -344,30 +372,43 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             height: metadata.height,
             colours: metadata.colours,
         });
-        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);
+        bitmap = await renderer.render(fallbackPath, {
+            label: labelContext,
+            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;
+    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, 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,
-            pid: target.pid,
-            aesKey: device.aesKey,
-            connectTimeoutMs,
-            reframe: device.reframe,
-            mirror: device.mirror,
-            compress: device.compress,
-            compressionFormat: device.compressionFormat,
-            gattBackend,
+    const attempts = Math.max(1, device.advanced?.paintRetries ?? config.paintRetries);
+    const paintWithRetries = () => {
+        // Rendering (or waiting for `exclusiveBleManagerAccess`) can outlast a `stop()` - don't open a
+        // BLE session for a plugin that's already stopping.
+        if (isStopping())
+            throw new Error("plugin stopping - paint skipped");
+        return (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
+            app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
+            const startedAt = Date.now();
+            const paint = driver.paint(bitmap, {
+                address,
+                pid: target.pid,
+                aesKey: device.advanced?.aesKey,
+                connectTimeoutMs,
+                reframe: device.advanced?.reframe,
+                mirror: device.advanced?.mirror,
+                compress: device.advanced?.compress,
+                compressionFormat: device.advanced?.compressionFormat,
+                writeWithoutResponse: device.advanced?.writeWithoutResponse,
+                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,
+            onError: (err, attempt) => app.debug(`${label}: paint attempt ${attempt}/${attempts} failed: ${err.message}`),
+            shouldStop: isStopping,
         });
-        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
@@ -378,10 +419,53 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     }
     app.debug(succeeded ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)` : `${label}: repainted fallback warning`);
 }
+function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
+    const inProgress = new Map();
+    const followUps = new Map();
+    let closed = false;
+    const call = async (arg) => {
+        if (closed)
+            return;
+        const key = keyOf(arg);
+        if (inProgress.has(key)) {
+            followUps.set(key, arg);
+            onBusy(arg);
+            return;
+        }
+        const running = run(arg);
+        inProgress.set(key, running);
+        let succeeded = false;
+        try {
+            succeeded = await running;
+        }
+        finally {
+            inProgress.delete(key);
+        }
+        const followUp = followUps.get(key);
+        followUps.delete(key);
+        if (followUp !== undefined && succeeded) {
+            await call(followUp);
+        }
+    };
+    return Object.assign(call, {
+        close() {
+            closed = true;
+            followUps.clear();
+        },
+        async idle() {
+            // A follow-up can start as an earlier run settles (unless closed), so loop until nothing is left.
+            while (inProgress.size > 0) {
+                await Promise.allSettled(inProgress.values());
+            }
+        },
+    });
+}
 function startRepaintScheduler(app, config) {
     const state = loadState(app);
     const unsubscribes = [];
     const getApiUrl = (0, resolveApiUrl_1.createApiUrlResolver)(config.signalkApiUrl);
+    let stopping = false;
+    const isStopping = () => stopping;
     // The first minute or two of a SignalK server's life is a chaos of plugin dependency sequencing -
     // a repaint attempted before other plugins (e.g. derived-data) have published the data a template
     // needs renders with missing/wrong values, and hash dedup (see `considerRepaint`) then means it
@@ -389,17 +473,19 @@ function startRepaintScheduler(app, config) {
     // (startup check, interval, subscription alike) funnels through this one gate.
     const startedAt = Date.now();
     const settleMs = (config.settleSeconds ?? 120) * 1000;
-    const repaint = async (device) => {
+    const repaint = oneAtATimePerKey((device) => device.friendlyName, (device) => repaintOnce(device), (device) => app.debug(`"${device.friendlyName}": already repainting - will check again once it's done`));
+    /** Returns whether every target was repainted (or was already up to date). */
+    const repaintOnce = async (device) => {
         const elapsedMs = Date.now() - startedAt;
         if (elapsedMs < settleMs) {
             app.debug(`"${device.friendlyName}": still settling (${Math.round(elapsedMs / 1000)}s/${Math.round(settleMs / 1000)}s) - skipping repaint`);
-            return;
+            return false;
         }
         const targets = await resolveTargets(app, config, device);
         if (targets.length === 0) {
-            return;
+            return false;
         }
-        const results = await Promise.allSettled(targets.map((target) => considerRepaint(app, config, device, target, state, getApiUrl)));
+        const results = await Promise.allSettled(targets.map((target) => considerRepaint(app, config, device, target, state, getApiUrl, isStopping)));
         results.forEach((result, i) => {
             if (result.status === "rejected") {
                 app.debug(`"${device.friendlyName}" [${targets[i].address}]: repaint failed: ${result.reason.message}`);
@@ -408,9 +494,11 @@ 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")) {
+        const allSucceeded = results.every((result) => result.status === "fulfilled");
+        if (device.advanced?.forceRepaint && allSucceeded) {
             clearForceRepaint(app, device.friendlyName);
         }
+        return allSucceeded;
     };
     const intervalDevices = config.devices.filter((device) => device.repaintTrigger === "interval");
     if (intervalDevices.length > 0) {
@@ -455,7 +543,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);
@@ -471,9 +559,22 @@ function startRepaintScheduler(app, config) {
     }, settleMs);
     unsubscribes.push(() => clearTimeout(startupCheckTimer));
     return {
-        stop() {
+        async stop() {
+            stopping = true;
             for (const unsubscribe of unsubscribes)
                 unsubscribe();
+            repaint.close();
+            let timer;
+            const drained = await Promise.race([
+                repaint.idle().then(() => true),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(false), exports.STOP_DRAIN_TIMEOUT_MS);
+                }),
+            ]);
+            clearTimeout(timer);
+            if (!drained) {
+                app.debug(`a repaint was still running ${exports.STOP_DRAIN_TIMEOUT_MS / 1000}s after stop - not waiting any longer`);
+            }
         },
     };
 }

package/dist/resolveApiUrl.js

@@ -37,6 +37,9 @@ async function probe(url) {
  * and uses the first that responds.
  */
 async function resolveSignalkApiUrl(configuredUrl) {
+    // Typed free-form in the config UI, so tolerate stray whitespace and a trailing slash, which would
+    // otherwise double up with the leading slash of every API path appended to it.
+    configuredUrl = configuredUrl?.trim().replace(/\/+$/, "") || undefined;
     const candidates = configuredUrl ? [configuredUrl] : exports.SIGNALK_API_URL_OPTIONS;
     for (const url of candidates) {
         if (await probe(url))

package/docs/bluetooth.md

@@ -0,0 +1,191 @@
+# Bluetooth
+
+Advice for getting a reliable Bluetooth Low Energy (BLE) connection between the SignalK server and your labels.
+
+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
+
+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))
+- CSR4.0 dongles (CSR8510 chip) have had kernel support for years, and there are well known work arounds for some of them, including in the Linux kernel since v5.17
+- Some Raspberry Pi models come with suitable Bluetooth built in
+- See advice at [Recommended Bluetooth Adapters for Linux](https://github.com/morrownr/USB-WiFi/blob/main/home/Recommended_Bluetooth_Adapters_for_Linux.md)
+- Bluetooth adapters typically prefer being in USB2.0 ports rather than USB3.0 ports, since often the USB3.0 implementation leaks radio energy on the same 2.4Ghz spectrum as Bluetooth. If no USB2.0 port available, try a shielded USB2.0 extension lead to distance the dongle from the port. Some dongle manufacturees seems to do a better job at shielding for this than others.
+
+> - 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.
+
+## BLE Manager Readiness
+
+v2.31.0 is the minumum version of SignalK possible for BLE Manager. Several fixes went in to v2.33.0 so this is the practical minimum version for using the plugin.
+
+Gicisky labels have been painted successfully using BLE Manager, however Zhsunyco have some different interactions that are waiting other fixes.
+
+- [PR#3082](https://github.com/SignalK/signalk-server/pull/3082) - hung connections locking up device
+- [PR#3088](https://github.com/SignalK/signalk-server/pull/3088) - Support plain GATT write requests
+- [PR#3089](https://github.com/SignalK/signalk-server/pull/3089) - Pause scanning while GATT operation in progress
+
+There's a workaround for **PR#3088** available in the _Advanced Options_, and **PR#3082** isn't a problem if operations don't fail, however **PR#3089** is a blocker for using Zhsunyco labels - they'll fail with a `0x0e` error code.
+
+## 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.
+
+If you're having problems with Bluetooth connections, make sure other plugins are well behaved, using BLE Manager where they can, and consider temporarily switching them off if needed to debug label connections.
+
+## SignalK in Docker
+
+Check for the `bluetooth` service working at both host level and inside the SignalK container. If there are stability issues, stop and disable the host level service (for example `sudo systemctl stop bluetooth` on a systemd controlled host).
+
+## Stuck Bluetooth Adapters
+
+Sometime Bluetooth adapters, and/or the Linux services that use them, can get into a 'stuck' state, where the only solution is to reboot the server (although unplugging and plugging the dongle may help). The best way to avoid this is using a known good dongle, and using BLE Manager in SignalK wherever possible.
+
+## Zhsunyco Labels and the BLE Manager
+
+With the "Use the SignalK BLE Manager API" setting on, Zhsunyco labels can connect and authenticate, then fail as soon as the image upload starts, with `Operation failed with ATT error: 0x0e` in the log. SignalK's BLE Manager (2.33 and earlier) sends every write that waits for an acknowledgement as a Bluetooth "reliable" write, which these labels don't support.
+
+Either:
+
+- turn on _Send image without waiting for each write (Zhsunyco)_ in the label's _Advanced settings_ - the image is sent with a small gap between writes instead, and the label still confirms once the whole image has arrived; or
+- switch the BLE Manager setting off, if no other plugins need to share Bluetooth with this one.
+
+Gicisky labels aren't affected, since they don't use acknowledged writes.
+
+## Stuck Labels
+
+A label can itself get into a stuck state - usually after several connections were cut off part way through a repaint - where it still advertises and accepts connections, but no longer lists its services. Every repaint then connects and fails a couple of seconds later, with `Service not available` in this plugin's log, or `Characteristic … was not found` from other software such as Home Assistant.
+
+You can confirm it's the label rather than your server: `bluetoothctl info <label address>` shows no `UUID:` lines even after a connection, and the same failure happens from a different adapter or computer.
+
+The fix is to power-cycle the label - take the battery out for 10-20 seconds, put it back, then trigger a repaint (for example with _Force repaint_). If it still fails, the manufacturer's own app may be needed to reset it.
+
+## Tuning Bluetooth Connections
+
+Labels spend most of their time asleep, so they can be slow to accept a connection, and slow to answer while an image is being sent to them. Linux's Bluetooth defaults are set with phones, headphones and sensors in mind, so if connections to labels regularly time out, or drop partway through a repaint (for example with GATT or connection-abort errors in the log), some Bluetooth settings on the server may need adjusting:
+
+- **The plugin's own timeouts** - the _Paint connect timeout_ and _Paint retries_, set plugin-wide or per label (see [Setting up a Label](getting-started.md#setting-up-a-label)). Try these first, since they only affect this plugin.
+- **BlueZ's connection settings**, in the `[LE]` section of `/etc/bluetooth/main.conf` - the connection interval range (`MinConnectionInterval`/`MaxConnectionInterval`), how long a quiet connection is kept before it's dropped (`ConnectionSupervisionTimeout`), and how long a connection attempt waits (`Autoconnecttimeout`). The file's own comments describe each one. Restart the Bluetooth service after changing it.
+- **The kernel's Bluetooth settings** for the adapter, under `/sys/kernel/debug/bluetooth/hci0/` - such as `supervision_timeout`, `conn_min_interval` and `conn_max_interval`. Values written here are lost on reboot, unless something re-applies them at startup.
+
+These apply whenever the server's Bluetooth goes through BlueZ, including the SignalK BLE Manager with a local adapter. They affect every Bluetooth device the server talks to, not just labels, so change one thing at a time and check that your other Bluetooth equipment still works.
+
+No particular values are recommended here - what works depends on the adapter, the labels and whatever else is using Bluetooth. Get advice before changing them, for example from the [SignalK community](https://signalk.org) or Home Assistant's Bluetooth community, where many of the same adapters and Linux setups are used.
+
+## SignalK starts before the Bluetooth daemon
+
+This and the next section are about direct BlueZ mode only - if the "Use the SignalK BLE Manager API" setting is enabled, adapter/dongle lifecycle is the SignalK server's problem to manage once, for every BLE-consuming plugin, not this plugin's.
+
+The plugin retries BLE adapter initialisation with backoff (starting at 2s, capping at 30s) if `bluetoothd`/D-Bus isn't up yet when the plugin starts, so a slow-starting Bluetooth stack on boot will no longer strand it — it keeps retrying until the adapter appears rather than failing once and giving up. You'll see `BLE adapter not ready … — retrying in Ns …` in the SignalK logs in the meantime.
+
+That said, it's cleaner to fix the boot ordering at the systemd level so the plugin finds the adapter ready on its first attempt. If SignalK runs as a systemd service (`systemctl status signalk`) and its unit file has no `[Unit]` section (check with `systemctl cat signalk`), add one:
+
+```bash
+sudo systemctl edit signalk.service
+```
+
+This opens an override file — add:
+
+```ini
+[Unit]
+After=bluetooth.target
+Wants=bluetooth.target
+```
+
+Save and exit, then:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart signalk
+```
+
+This tells systemd to start `bluetoothd` first and wait for it before starting SignalK, rather than relying on both racing to start in parallel at boot.
+
+## Adapter stops responding: "No gpio to reset"
+
+Example log:
+
+```
+Bluetooth: hci0: No gpio to reset Realtek device, ignoring
+Bluetooth: hci0: Unable to disable scanning: -110
+Bluetooth: hci0: command 0x2042 tx timeout
+Bluetooth: hci0: Opcode 0x2042 failed: -110
+```
+
+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
+
+> [!Note]
+> In these examples the dongle is for vendor `0b05` and product `190e`, adapt for your own devices, use `lsusb` to find out, and if there's no `lsusb` command, install the `usbutils` package.
+
+Following file created at `/etc/udev/rules.d/99-bt500-no-autosuspend.rules`
+
+```
+# Disable USB autosuspend for the ASUS USB-BT500 (RTL8761BU, 0b05:190e).
+ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="0b05", ATTR{idProduct}=="190e", TEST=="power/control", ATTR{power/control}="on"
+```
+
+### Example tlp fix
+
+If `tlp` running to minimize power, it may have its own rules trying to suspend the Bluetooth dongle.
+
+Following file created at /etc/tlp.d/99-bt500-no-autosuspend.conf
+
+```
+USB_DENYLIST="0b05:190e"
+```
+
+## Bluetooth Jargon Buster
+
+Bluetooth comes with a lot of acronyms. Here's what the ones on this page mean, without needing to be a computer person.
+
+When the plugin paints a label, the request goes down a chain: the plugin asks **BlueZ** over **D-Bus**, BlueZ gives orders to the Bluetooth dongle over **HCI**, and the dongle's radio talks to the label using **BLE**, reading and writing the label's **GATT** services. A **gateway** or **proxy** simply moves the radio end of that chain somewhere else on the boat.
+
+- **BLE (Bluetooth Low Energy)** - the kind of Bluetooth made for small battery-powered gadgets like labels, sensors and battery monitors.
+  - It's different from the "classic" Bluetooth used by headphones and speakers, and doesn't have the usual pairing process.
+  - BLE devices talk in short bursts and sleep in between, which is how a label runs for years on a coin cell.
+  - They regularly broadcast short "advertisements" saying who they are, and the server picks these up by _scanning_.
+  - BLE needs an adapter supporting Bluetooth 4.0 or later.
+- **HCI (Host Controller Interface)** - the standard set of commands a computer uses to give orders to a Bluetooth radio chip, such as "start scanning" or "connect to this device".
+  - Linux names each Bluetooth adapter after it, so `hci0` is the first adapter, `hci1` the second, and so on.
+  - A plugin using the adapter "directly" is sending HCI commands itself, works fine if there's only one Bluetooth app on the server.
+- **BlueZ** - the standard Bluetooth software on Linux.
+  - It runs quietly in the background as a service called `bluetoothd`, takes charge of the adapter, keeps a list of the devices it has heard, and handles connecting to them.
+  - Its a sane alternative to multiple Linux programs all trying to grab the limited resources of the Bluetooth adapter and stomping over each other. It does at a Linux level what BLE Manager does for SignalK - a single point of ownership and control over a contested resource.
+- **D-Bus** - the messaging system that programs on a Linux computer use to talk to each other.
+  - It's how the plugin, or SignalK's BLE Manager, asks BlueZ to scan or connect.
+  - If you know NMEA 2000, it's a similar idea: one shared backbone that everything plugs into and exchanges messages over, rather than a separate cable between every pair of devices.
+- **GATT (Generic Attribute Profile)** - how a BLE device organises what it offers once you're connected to it.
+  - The device has _services_, each a group of related features, and each service has _characteristics_, individual values you can read, write or be told about when they change.
+  - Painting a label means connecting, finding its image service, and writing the picture into the right characteristic a piece at a time.
+  - The "GATT claims" shown in SignalK's BLE Manager are simply which plugin has booked which device for a connection, so that two plugins don't try to talk to it at once.
+- **Gateway** - a separate small device, often a cheap ESP32 board, with its own Bluetooth radio, which listens for and talks to BLE devices near it and relays everything to SignalK over the boat's network.
+  - It's effectively fitting a remote antenna closer to where it's needed: useful when a label is too far from the server, or on a big boat that needs more than one. SignalK's BLE Manager can use gateways alongside, or instead of, a local adapter.
+- **Proxy** - much the same idea as a gateway: a device that does the Bluetooth radio work on the server's behalf, somewhere with a better signal.
+  - Different software uses different names for it. Home Assistant users, for example, will know ESP32 "Bluetooth proxies".