@rhizomatics/signalk-einklabel-plugin 1.3.0-beta8 → 1.3.0

package/dist/render/llmPrompt.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLabelContext = buildLabelContext;
+exports.findPromptBindings = findPromptBindings;
+exports.substitutePlaceholders = substitutePlaceholders;
+exports.extractSvg = extractSvg;
+exports.loadOptional = loadOptional;
+exports.callLlm = callLlm;
+const binding_1 = require("./binding");
+const formatters_1 = require("./formatters");
+const COLOUR_HEX = { black: "#000000", white: "#FFFFFF", red: "#FF0000", yellow: "#FFFF00" };
+/** The only `font-family` values `SvgRenderer` is guaranteed to render - see `expandGenericFontFamilies` in `./svgRenderer.ts`. */
+const SAFE_FONT_FAMILIES = ["serif", "sans-serif", "monospace"];
+/**
+ * Builds the `context.label` object a prompt/target-guidance fragment addresses via
+ * `source=label,path=...` bindings (e.g. `{source=label,path=width}`, or the bare-path shorthand
+ * `{width}` is *not* supported here deliberately - see `./binding.ts`'s `parseBinding`, every `{...}`
+ * placeholder is a real binding, so a `label` path always needs the explicit `source=label,path=`
+ * form to disambiguate it from a `signalk` self path). `colours`/`fonts` are left as arrays (each
+ * colour entry pre-annotated with its hex code, e.g. `"black (#000000)"`) rather than joined into a
+ * single string, so a prompt author can either use them bare (renders as JSON, e.g. for a model that
+ * parses structured hints) or add `format=csv` (see `./formatters.ts`) for a plain comma-separated list.
+ */
+function buildLabelContext(meta) {
+    return {
+        manufacturer: meta.manufacturer,
+        label: meta.label,
+        width: meta.width,
+        height: meta.height,
+        colours: meta.colours.map((colour) => `${colour} (${COLOUR_HEX[colour]})`),
+        fonts: SAFE_FONT_FAMILIES,
+        description: meta.description ?? "",
+        position: meta.position ? (0, formatters_1.applyFormat)("position", meta.position, {}, 3) : undefined,
+    };
+}
+/**
+ * Every binding referenced across one or more prompt fragments - every `{...}` placeholder, deduplicated
+ * across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
+ * (`parseBinding`, see `./binding.ts`), so a bare path (`{design.length}`, `source=signalk,context=self`
+ * shorthand), the full binding grammar (`{source=signalk,path=navigation.position,format=position}`),
+ * and a `source=label,path=...` binding all work uniformly. Pass the result to `assembleRawContext`
+ * (repaintScheduler.ts) exactly as a template's own bindings are - it fetches the `signalk`/
+ * `resources`-sourced ones and silently ignores `label`/`einklabel`-sourced ones, which resolve directly
+ * against `context.label`/`context.meta` instead (built by the caller, not fetched).
+ *
+ * A placeholder that isn't valid binding grammar (e.g. a typo like `{source=taheight}`) is silently
+ * skipped here rather than thrown - the same per-field isolation `SvgRenderer` gives a bad `<desc>`
+ * binding, so one malformed placeholder doesn't take down the whole prompt. `substitutePlaceholders`
+ * hits the identical parse error at substitution time and turns it into "???" for just that field.
+ */
+function findPromptBindings(...texts) {
+    const seen = new Set();
+    const bindings = [];
+    for (const text of texts) {
+        for (const match of text.matchAll(/\{([^{}]+)\}/g)) {
+            const key = match[1].trim();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            try {
+                bindings.push((0, binding_1.parseBinding)(key));
+            }
+            catch {
+                // see doc comment above - left for `substitutePlaceholders` to turn into "???"
+            }
+        }
+    }
+    return bindings;
+}
+/**
+ * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
+ * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
+ * `findPromptBindings`). Mirrors `renderBinding`'s per-field isolation, but substitutes "???" for
+ * anything that resolves to no value at all (missing path, invalid binding grammar) rather than "" -
+ * prose with a silently-blank word reads as a fact ("for the sailor of a m vessel"), not as a gap the
+ * reader would notice. Two things override that "???": a binding that resolves successfully to a
+ * legitimately empty string (e.g. an unset `{source=label,path=description}`) is left as empty, since
+ * that's a real answer, not a miss; and a binding with an explicit `default=` (see `./binding.ts`) uses
+ * that default instead, since the prompt author has already said what a missing value should read as.
+ */
+function substitutePlaceholders(text, context) {
+    return text.replace(/\{([^{}]+)\}/g, (_match, raw) => {
+        const key = raw.trim();
+        try {
+            const binding = (0, binding_1.parseBinding)(key);
+            const value = (0, binding_1.resolveBinding)(binding, context);
+            if ((value === undefined || value === null) && binding.default === undefined)
+                return "???";
+            return (0, binding_1.renderBinding)(binding, context);
+        }
+        catch {
+            return "???";
+        }
+    });
+}
+/**
+ * Strips everything outside the first `<svg`...last `</svg>` span - a chat model asked for "only raw
+ * SVG markup" still often wraps it in a markdown code fence or adds a sentence of commentary either
+ * side, despite the target-guidance fragment telling it not to.
+ */
+function extractSvg(raw) {
+    const start = raw.indexOf("<svg");
+    const end = raw.lastIndexOf("</svg>");
+    if (start === -1 || end === -1 || end < start) {
+        throw new Error('LLM response did not contain a "<svg>...</svg>" document');
+    }
+    return raw.slice(start, end + "</svg>".length);
+}
+/**
+ * `ai` and every `@ai-sdk/*` provider package are `optionalDependencies` (see package.json), not plain
+ * `dependencies` - most installs (every device using `renderMode: "svg-template"` only) never touch an
+ * LLM at all, so they shouldn't have to pull in this whole gateway stack, and an install that fails to
+ * fetch one of these (network hiccup, `npm install --omit=optional`, an unsupported platform) must not
+ * break BLE painting/templates, which have nothing to do with it. That means every reference to one of
+ * these packages has to be a `require()` reached only when a `renderMode: "llm-prompt"` device actually
+ * calls `callLlm` - a top-level `import` would be resolved eagerly the moment this module loads (which
+ * is every plugin start, via `repaintScheduler.ts`), throwing before any config is even read. Types are
+ * still fully checked via `typeof import(...)` below, which - unlike a value `import` - is erased
+ * entirely at compile time and leaves no runtime trace for `tsc` to eagerly require.
+ */
+function loadOptional(moduleName) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require(moduleName);
+    }
+    catch (err) {
+        throw new Error(`LLM provider support needs the optional dependency "${moduleName}", which isn't installed - run "npm install ${moduleName}" (${err.message})`);
+    }
+}
+/** Ollama's own default local listen address - see the `"ollama"` case in `resolveModel` below. */
+const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
+/**
+ * Resolves `settings` to a Vercel AI SDK model handle. `"ollama"` and `"local"` both go through the
+ * generic `@ai-sdk/openai-compatible` provider (Ollama/LM Studio/vLLM all expose an OpenAI-compatible
+ * endpoint, and none of them has - or needs - its own dedicated `@ai-sdk/*` package): `"ollama"`
+ * defaults `llmBaseUrl` to Ollama's own standard local address so it works with no further config
+ * (override it only if Ollama is running elsewhere, e.g. on the SignalK server's own host reached over
+ * the network); `"local"` is for anything else OpenAI-compatible, where there's no sensible universal
+ * default, so `llmBaseUrl` is required.
+ */
+function resolveModel(settings) {
+    const model = settings.llmModel;
+    if (!model) {
+        throw new Error("no LLM model configured (PluginConfig.llmModel)");
+    }
+    switch (settings.llmProvider ?? "openai") {
+        case "anthropic": {
+            const { createAnthropic } = loadOptional("@ai-sdk/anthropic");
+            return createAnthropic({ apiKey: settings.llmApiKey })(model);
+        }
+        case "google": {
+            const { createGoogleGenerativeAI } = loadOptional("@ai-sdk/google");
+            return createGoogleGenerativeAI({ apiKey: settings.llmApiKey })(model);
+        }
+        case "xai": {
+            const { createXai } = loadOptional("@ai-sdk/xai");
+            return createXai({ apiKey: settings.llmApiKey })(model);
+        }
+        case "ollama": {
+            const { createOpenAICompatible } = loadOptional("@ai-sdk/openai-compatible");
+            return createOpenAICompatible({
+                name: "ollama",
+                baseURL: settings.llmBaseUrl || DEFAULT_OLLAMA_BASE_URL,
+                apiKey: settings.llmApiKey,
+            })(model);
+        }
+        case "local": {
+            if (!settings.llmBaseUrl) {
+                throw new Error('llmBaseUrl is required when llmProvider is "local"');
+            }
+            const { createOpenAICompatible } = loadOptional("@ai-sdk/openai-compatible");
+            return createOpenAICompatible({ name: "local", baseURL: settings.llmBaseUrl, apiKey: settings.llmApiKey })(model);
+        }
+        case "openai":
+        default: {
+            const { createOpenAI } = loadOptional("@ai-sdk/openai");
+            return createOpenAI({ apiKey: settings.llmApiKey })(model);
+        }
+    }
+}
+/**
+ * Calls the configured LLM gateway with `prompt`, returning its raw text response - not yet extracted/
+ * validated as SVG, see `extractSvg`. This is the first network call in the codebase that needs its own
+ * timeout (`fetchJson` in `../httpJson.ts` has none - every existing call is to the local SignalK
+ * server's own REST API).
+ */
+async function callLlm(settings, prompt) {
+    const model = resolveModel(settings);
+    const { generateText } = loadOptional("ai");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), (settings.llmTimeoutSeconds ?? 30) * 1000);
+    try {
+        const { text } = await generateText({ model, prompt, abortSignal: controller.signal });
+        return text;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/render/mirror.d.ts

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

package/dist/render/mirror.js

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

package/dist/repaintScheduler.d.ts

@@ -13,4 +13,12 @@ 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.
+ */
+export declare function oneAtATimePerKey<T>(keyOf: (arg: T) => string, run: (arg: T) => Promise<boolean>, onBusy?: (arg: T) => void): (arg: T) => Promise<void>;
 export declare function startRepaintScheduler(app: ServerAPI, config: PluginConfig): RepaintScheduler;

package/dist/repaintScheduler.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mostRecentScheduledSlot = mostRecentScheduledSlot;
+exports.oneAtATimePerKey = oneAtATimePerKey;
 exports.startRepaintScheduler = startRepaintScheduler;
 const crypto_1 = require("crypto");
 const path_1 = require("path");
@@ -25,6 +26,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
@@ -175,7 +183,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}`);
@@ -260,6 +268,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 +306,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 +319,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,6 +330,7 @@ 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 ?? "",
             },
         };
@@ -327,7 +338,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             ? await provider.render({ templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours })
             : await renderer.render(templatePath, renderContext, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
         succeeded = true;
-        repaintReason = device.forceRepaint
+        repaintReason = device.advanced?.forceRepaint
             ? "forced"
             : provider
                 ? "provider-rendered"
@@ -344,22 +355,31 @@ 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 attempts = Math.max(1, device.advanced?.paintRetries ?? config.paintRetries);
     const paintWithRetries = () => (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
         app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
         const startedAt = Date.now();
-        await driver.paint(bitmap, {
+        const paint = driver.paint(bitmap, {
             address,
             pid: target.pid,
-            aesKey: device.aesKey,
+            aesKey: device.advanced?.aesKey,
             connectTimeoutMs,
-            reframe: device.reframe,
+            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,
@@ -375,6 +395,39 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     }
     app.debug(succeeded ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)` : `${label}: repainted fallback warning`);
 }
+/**
+ * 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.
+ */
+function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
+    const inProgress = new Set();
+    const followUps = new Map();
+    const call = async (arg) => {
+        const key = keyOf(arg);
+        if (inProgress.has(key)) {
+            followUps.set(key, arg);
+            onBusy(arg);
+            return;
+        }
+        inProgress.add(key);
+        let succeeded = false;
+        try {
+            succeeded = await run(arg);
+        }
+        finally {
+            inProgress.delete(key);
+        }
+        const followUp = followUps.get(key);
+        followUps.delete(key);
+        if (followUp !== undefined && succeeded) {
+            await call(followUp);
+        }
+    };
+    return call;
+}
 function startRepaintScheduler(app, config) {
     const state = loadState(app);
     const unsubscribes = [];
@@ -386,15 +439,17 @@ 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)));
         results.forEach((result, i) => {
@@ -405,9 +460,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) {
@@ -452,7 +509,7 @@ function startRepaintScheduler(app, config) {
     // still avoids a redundant paint once targets are resolved.
     const startupCheckTimer = setTimeout(() => {
         for (const device of config.devices) {
-            if (device.repaintTrigger === "interval" && !device.forceRepaint && device.device !== config_1.ALL_DEVICES) {
+            if (device.repaintTrigger === "interval" && !device.advanced?.forceRepaint && device.device !== config_1.ALL_DEVICES) {
                 const hours = device.intervalHours ?? 1;
                 const minute = device.intervalMinute ?? 0;
                 const dueSlot = mostRecentScheduledSlot(new Date(), hours, minute);

package/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,162 @@
+# 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"
+```