@rhizomatics/signalk-einklabel-plugin 1.3.2 → 1.3.3

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+# 1.3.3
+
+## 🔐 SSL
+
+- New "Allow self-signed certificates" setting, off by default. A SignalK server with SSL enabled redirects its http port to https, usually with a self-signed certificate, which the plugin previously rejected - so templates using the SignalK REST API (`category=` or a resource pinned with `provider=`) failed to render and the label showed the fallback warning. Turn the setting on for a server like this.
+
+## 🐛 Bug fixes
+
+- A render failure that paints the fallback warning on a label is now logged as an error, with its cause, rather than only in debug logging
+- When the SignalK API URL can't be reached, the logged error now gives the underlying reason for each address tried, e.g. a self-signed certificate, rather than only suggesting the port or anonymous access; a certificate failure points to the new setting
+
+## BLE Manager
+
+- The "Use the SignalK BLE Manager API" setting is now on by default. Servers without BLE Manager (before v2.31.0) fall back to direct BlueZ access, and existing configs that already saved the setting keep their value
+- Recent SignalK versions identify Zhsunyco labels by manufacturer, shown as "WOESL" in the BLE Manager device list
+
 # 1.3.2
 
 ## 🐛 Bug fixes

package/dist/config.d.ts

@@ -107,8 +107,9 @@ export interface PluginConfig {
     /**
      * Route BLE access through the SignalK server's BLE Manager API (`app.bleApi`, 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 - see `bleBackend.ts`. Off by default, and only ever offered in the
-     * config schema when the running server actually has `app.bleApi` (see `configSchema` below).
+     * instead of contending for it - see `bleBackend.ts`. On by default; a server without `app.bleApi`
+     * falls back to direct BlueZ access (see `plugin.ts`), and the option is only ever offered in the
+     * config schema when the running server actually has it (see `configSchema` below).
      */
     useBleApi: boolean;
     /** How long to wait for a device to accept a BLE connection before giving up on a repaint attempt, in seconds. */
@@ -140,6 +141,11 @@ export interface PluginConfig {
      * anonymous read access - the plugin has no login flow.
      */
     signalkApiUrl?: string;
+    /**
+     * Accept a self-signed TLS certificate on the plugin's calls to `signalkApiUrl` - see
+     * `setAllowSelfSignedCertificates` in `./httpJson.ts`. Off by default, so certificates are verified.
+     */
+    allowSelfSignedCertificates: boolean;
     devices: DeviceConfig[];
 }
 /**

package/dist/config.js

@@ -99,10 +99,11 @@ function defaultConfig() {
         templatesDir: "",
         scanOnStart: false,
         scanDurationSeconds: 20,
-        useBleApi: false,
+        useBleApi: true,
         paintConnectTimeoutSeconds: 30,
         paintRetries: 3,
         settleSeconds: 120,
+        allowSelfSignedCertificates: false,
         devices: [],
     };
 }
@@ -115,6 +116,7 @@ const PLUGIN_CONFIG_KEYS = [
     "paintRetries",
     "settleSeconds",
     "signalkApiUrl",
+    "allowSelfSignedCertificates",
     "devices",
 ];
 /**
@@ -464,6 +466,13 @@ function configSchema(app, discovered = []) {
                 examples: resolveApiUrl_1.SIGNALK_API_URL_OPTIONS,
                 pattern: "^(\\s*|\\s*https?://\\S+\\s*)$",
             },
+            allowSelfSignedCertificates: {
+                type: "boolean",
+                title: "Allow self-signed certificates",
+                description: "Accept a self-signed certificate when calling the SignalK API above. Needed when the server has SSL enabled with its own " +
+                    "generated certificate - its http port then redirects to https, which otherwise fails certificate checks. Leave off unless needed.",
+                default: defaults.allowSelfSignedCertificates,
+            },
             devices: {
                 type: "array",
                 title: "Devices",

package/dist/httpJson.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Whether `fetchJson` accepts a self-signed (or otherwise unverifiable) TLS certificate. Off by default,
+ * so certificates are verified exactly as plain `fetch()` does. Set from the plugin's
+ * `allowSelfSignedCertificates` config on each start - a SignalK server with SSL enabled redirects its http
+ * port to https, usually with a self-signed certificate, which `fetch()` otherwise always rejects. Process-wide
+ * rather than per call, since every `fetchJson` call in the plugin goes to that one server's own API.
+ */
+export declare function setAllowSelfSignedCertificates(allowed: boolean): void;
 /**
  * Fetches and parses a JSON endpoint, with an error message that's actually actionable: which URL,
  * what HTTP status, and the response/underlying error detail - see `describeCause` for why plain

package/dist/httpJson.js

@@ -1,6 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAllowSelfSignedCertificates = setAllowSelfSignedCertificates;
 exports.fetchJson = fetchJson;
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+/** How many redirects the self-signed path follows before giving up - `fetch()`'s own default is 20. */
+const MAX_REDIRECTS = 5;
+/** Per-request deadline on the self-signed path, which has none of `fetch()`'s built-in timeouts. */
+const REQUEST_TIMEOUT_MS = 30000;
+let allowSelfSigned = false;
+/**
+ * Whether `fetchJson` accepts a self-signed (or otherwise unverifiable) TLS certificate. Off by default,
+ * so certificates are verified exactly as plain `fetch()` does. Set from the plugin's
+ * `allowSelfSignedCertificates` config on each start - a SignalK server with SSL enabled redirects its http
+ * port to https, usually with a self-signed certificate, which `fetch()` otherwise always rejects. Process-wide
+ * rather than per call, since every `fetchJson` call in the plugin goes to that one server's own API.
+ */
+function setAllowSelfSignedCertificates(allowed) {
+    allowSelfSigned = allowed;
+}
 /**
  * Describes a network-level fetch failure's `error.cause` - Node's `fetch()` only ever throws a
  * generic `TypeError: fetch failed`, with the actually useful detail (e.g. ECONNREFUSED) nested in
@@ -23,6 +41,8 @@ function describeCause(cause) {
  * `fetch()` failures need unwrapping to be useful at all.
  */
 async function fetchJson(url) {
+    if (allowSelfSigned)
+        return fetchJsonAllowingSelfSigned(url);
     let response;
     try {
         response = await fetch(url);
@@ -30,7 +50,7 @@ async function fetchJson(url) {
     catch (err) {
         const cause = err.cause;
         const detail = cause !== undefined ? describeCause(cause) : err.message;
-        throw new Error(`fetch failed: ${url} - ${detail}`);
+        throw new Error(`fetch failed: ${url} - ${detail}${certificateHint(detail)}`);
     }
     if (!response.ok) {
         const body = await response.text().catch(() => "");
@@ -38,3 +58,60 @@ async function fetchJson(url) {
     }
     return response.json();
 }
+/** Points a certificate failure at the setting that fixes it, since the raw TLS error doesn't. */
+function certificateHint(detail) {
+    return /certificate|CERT_/i.test(detail)
+        ? ' - if this server uses a self-signed certificate, enable "Allow self-signed certificates" in the plugin config'
+        : "";
+}
+/**
+ * `fetchJson` over `node:http`/`node:https` with certificate verification off - built-in `fetch()` has no
+ * per-request way to skip it without the separate `undici` package. Follows redirects itself (the http to
+ * https redirect being the usual reason to need this at all), with the same error messages as `fetchJson`.
+ */
+async function fetchJsonAllowingSelfSigned(url) {
+    let current = url;
+    for (let redirects = 0;; redirects++) {
+        let response;
+        try {
+            response = await sendGet(current);
+        }
+        catch (err) {
+            throw new Error(`fetch failed: ${url} - ${describeCause(err)}`);
+        }
+        const status = response.statusCode ?? 0;
+        const location = response.headers.location;
+        if (status >= 300 && status < 400 && location) {
+            response.resume();
+            if (redirects >= MAX_REDIRECTS)
+                throw new Error(`fetch failed: ${url} - more than ${MAX_REDIRECTS} redirects`);
+            current = new URL(location, current).toString();
+            continue;
+        }
+        const body = await readBody(response).catch(() => "");
+        if (status < 200 || status >= 300) {
+            throw new Error(`fetch failed: ${url} (${status} ${response.statusMessage ?? ""})${body ? ` - ${body}` : ""}`);
+        }
+        return JSON.parse(body);
+    }
+}
+function sendGet(url) {
+    return new Promise((resolve, reject) => {
+        const target = new URL(url);
+        const headers = { accept: "application/json" };
+        const request = target.protocol === "https:"
+            ? (0, node_https_1.request)(target, { headers, rejectUnauthorized: false }, resolve)
+            : (0, node_http_1.request)(target, { headers }, resolve);
+        request.setTimeout(REQUEST_TIMEOUT_MS, () => request.destroy(new Error(`no response after ${REQUEST_TIMEOUT_MS / 1000}s`)));
+        request.on("error", reject);
+        request.end();
+    });
+}
+function readBody(response) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(chunk));
+        response.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        response.on("error", reject);
+    });
+}

package/dist/index.d.ts

@@ -15,11 +15,12 @@ import type { Bitmap as BitmapType, TemplateContext as TemplateContextType } fro
  * `start()` (or at module load time). There's no scanning of installed packages -
  * registration is always an explicit call by the extension's own code.
  *
- * Declare this package as a regular `dependency` in the extension package (**not** a
- * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
- * interacts poorly with the server's plugin install layout), and declare the SignalK-level
- * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
- * extension's own package.json instead, so the App Store can install/report the dependency.
+ * Declare the relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }`
+ * in the extension's own package.json, plus a `devDependency` for types/tests - **not** a regular
+ * `dependency` or `peerDependency`. The App Store installs required plugins flat in
+ * `~/.signalk/node_modules`, so the extension's `require` resolves the one copy the running plugin
+ * uses; a regular `dependency` can leave a nested copy with its own empty registry, and a
+ * `peerDependency` interacts poorly with the server's plugin install layout (SignalK's own guidance).
  */
 declare function plugin(app: ServerAPI): Plugin;
 declare namespace plugin {
@@ -30,7 +31,7 @@ declare namespace plugin {
      * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
      * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
      * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
-     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     * `signalk.requires`-plus-`devDependency` convention as `registerVendorDriver` above.
      */
     const registerTemplateProvider: typeof registerTemplateProviderImpl;
     const getTemplateProvider: typeof findTemplateProviderImpl;

package/dist/index.js

@@ -12,11 +12,12 @@ const binding_1 = require("./render/binding");
  * `start()` (or at module load time). There's no scanning of installed packages -
  * registration is always an explicit call by the extension's own code.
  *
- * Declare this package as a regular `dependency` in the extension package (**not** a
- * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
- * interacts poorly with the server's plugin install layout), and declare the SignalK-level
- * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
- * extension's own package.json instead, so the App Store can install/report the dependency.
+ * Declare the relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }`
+ * in the extension's own package.json, plus a `devDependency` for types/tests - **not** a regular
+ * `dependency` or `peerDependency`. The App Store installs required plugins flat in
+ * `~/.signalk/node_modules`, so the extension's `require` resolves the one copy the running plugin
+ * uses; a regular `dependency` can leave a nested copy with its own empty registry, and a
+ * `peerDependency` interacts poorly with the server's plugin install layout (SignalK's own guidance).
  */
 function plugin(app) {
     return (0, plugin_1.createPlugin)(app);
@@ -29,7 +30,7 @@ function plugin(app) {
      * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
      * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
      * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
-     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     * `signalk.requires`-plus-`devDependency` convention as `registerVendorDriver` above.
      */
     plugin.registerTemplateProvider = templateProviders_1.registerTemplateProvider;
     plugin.getTemplateProvider = templateProviders_1.findTemplateProvider;

package/dist/plugin.js

@@ -10,6 +10,7 @@ const bleDiscovery_1 = require("./devices/bleDiscovery");
 const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const repaintScheduler_1 = require("./repaintScheduler");
 const pluginVersion_1 = require("./pluginVersion");
+const httpJson_1 = require("./httpJson");
 /** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
 async function runStartupScan(app, durationSeconds, useBleApi) {
     const alreadyRunning = (0, discoveryCoordinator_1.scanInProgressSince)();
@@ -64,6 +65,7 @@ function createPlugin(app) {
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
             (0, config_1.healStoredConfig)(app);
+            (0, httpJson_1.setAllowSelfSignedCertificates)(pluginConfig.allowSelfSignedCertificates);
             const thisGeneration = ++generation;
             const isCurrent = () => thisGeneration === generation;
             const previousStop = stopping;

package/dist/render/templateProviders.d.ts

@@ -21,9 +21,9 @@ export interface TemplateRenderRequest {
  * Public extension point for a package that wants to offer an alternative way to produce a device's
  * content, alongside hand-authored SVG templates - e.g. `@rhizomatics/signalk-einklabel-genai-plugin`
  * generating content from an LLM prompt. Mirrors `VendorDriver`/`registerDriver`
- * (`../devices/registry.ts`): an extension declares this package as a regular `dependency` (**not** a
- * `peerDependency` - see `registerVendorDriver`'s own doc comment in `../index.ts` for why) plus
- * `"signalk": { "requires": [...] }` in its own package.json, calls `esl.registerTemplateProvider(...)`
+ * (`../devices/registry.ts`): an extension declares this package via `"signalk": { "requires": [...] }`
+ * plus a `devDependency` (**not** a regular `dependency` or `peerDependency` - see
+ * `registerVendorDriver`'s own doc comment in `../index.ts` for why), calls `esl.registerTemplateProvider(...)`
  * from its own SignalK plugin's `start()`, and its entries show up in the same "Template" dropdown as
  * ordinary `.svg` files, distinguished only by `suffix`.
  */

package/dist/repaintScheduler.js

@@ -178,7 +178,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
             // REST API's own `?provider=` query param doesn't have this bug (it queries only that provider),
             // so a pinned binding goes over HTTP instead of the in-process API to actually get what it asked for.
             if (!apiUrl) {
-                throw new Error(`binding pins resource "${binding.resource}" to provider "${binding.provider}" but no SignalK API base URL is configured`);
+                throw new Error(`binding pins resource "${binding.resource}" to provider "${binding.provider}" but the SignalK API base URL could not be resolved (see the earlier error)`);
             }
             resources[key] = await (0, httpJson_1.fetchJson)(`${apiUrl}${RESOURCES_API_PATH}/${binding.resource}?provider=${encodeURIComponent(binding.provider)}`);
         }
@@ -193,7 +193,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
     }
     const categoryNames = new Set(bindings.filter((binding) => binding.category).map((binding) => binding.category));
     if (categoryNames.size > 0 && !apiUrl) {
-        throw new Error(`binding references categor${categoryNames.size > 1 ? "ies" : "y"} "${[...categoryNames].join(", ")}" but no SignalK API base URL is configured`);
+        throw new Error(`binding references categor${categoryNames.size > 1 ? "ies" : "y"} "${[...categoryNames].join(", ")}" but the SignalK API base URL could not be resolved (see the earlier error)`);
     }
     const categories = apiUrl ? await (0, unitCategories_1.fetchCategoryDisplayUnits)(apiUrl, categoryNames) : {};
     return { signalk, resources, pathMeta, categories };
@@ -285,6 +285,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
     let dataHash = "";
     let paintDurationMs = 0;
     let repaintReason = "render failed";
+    let renderError = "";
     // 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"));
@@ -304,7 +305,9 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
     });
     try {
         const apiUrl = await getApiUrl().catch((err) => {
-            app.debug(`${label}: ${err.message}`);
+            // An error, not debug - templates that need the API (pinned resources, `category=`) fail to render
+            // without it, and this is the only place the underlying reason is reported.
+            app.error(`${label}: ${err.message}`);
             return undefined;
         });
         let bindings = [];
@@ -375,7 +378,10 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
                         : "data changed";
     }
     catch (err) {
-        app.debug(`${label}: render failed (${err.message}) - showing fallback warning`);
+        // An error, not debug - the label shows only a generic warning, so the server log is the one place
+        // the actual cause is visible, and it must be there without the plugin's debug logging enabled.
+        renderError = err.message;
+        app.error(`${label}: render failed (${renderError}) - showing fallback warning`);
         const fallbackPath = (0, config_1.resolveTemplatePath)(templatesDir, config_1.RENDER_FALLBACK_TEMPLATE_NAME, {
             width: metadata.width,
             height: metadata.height,
@@ -426,7 +432,9 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
         state[stateKey] = { templateHash, dataHash, repaintedAt: Date.now() };
         saveState(app, state);
     }
-    app.debug(succeeded ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)` : `${label}: repainted fallback warning`);
+    app.debug(succeeded
+        ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)`
+        : `${label}: repainted fallback warning (render failed: ${renderError})`);
 }
 function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
     const inProgress = new Map();

package/dist/resolveApiUrl.js

@@ -21,13 +21,14 @@ const httpJson_1 = require("./httpJson");
 exports.SIGNALK_API_URL_OPTIONS = ["http://localhost:3000", "http://localhost", "https://localhost"];
 /** Cheap, always-required (for `category=` resolution) and read-only, so safe to use as a connectivity+access probe. */
 const PROBE_PATH = "/signalk/v1/unitpreferences/categories";
+/** Resolves to `undefined` when `url` answers the probe, or to the failure's message when it doesn't. */
 async function probe(url) {
     try {
         await (0, httpJson_1.fetchJson)(`${url}${PROBE_PATH}`);
-        return true;
+        return undefined;
     }
-    catch {
-        return false;
+    catch (err) {
+        return err.message;
     }
 }
 /**
@@ -41,13 +42,19 @@ async function resolveSignalkApiUrl(configuredUrl) {
     // 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;
+    // Kept so the error says *why* each candidate failed - e.g. an http URL redirected to https with a
+    // self-signed certificate, which otherwise looks identical to a wrong port.
+    const failures = [];
     for (const url of candidates) {
-        if (await probe(url))
+        const failure = await probe(url);
+        if (failure === undefined)
             return url;
+        failures.push(failure);
     }
-    throw new Error(configuredUrl
+    throw new Error((configuredUrl
         ? `configured SignalK API base URL "${configuredUrl}" did not respond to ${PROBE_PATH} - check the port, and that anonymous read access is enabled`
-        : `could not reach this server's API on any of ${exports.SIGNALK_API_URL_OPTIONS.join(", ")} - it may be on a different port, or anonymous read access may not be enabled`);
+        : `could not reach this server's API on any of ${exports.SIGNALK_API_URL_OPTIONS.join(", ")} - it may be on a different port, or anonymous read access may not be enabled`) +
+        ` (${failures.join("; ")})`);
 }
 /**
  * Memoizes a successful resolution only - a failure (server not ready yet, anonymous access

package/docs/bluetooth.md

@@ -6,11 +6,11 @@ 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.
+- Using the BLE Manager added to SignalK in 2026. Recommended, and the default for this plugin.
+  - With the "Use the SignalK BLE Manager API" setting enabled (the default), 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
+  - On a server without BLE Manager (before v2.31.0) the plugin falls back to direct `bluez` access
 
 The advice here is general to Bluetooth on Linux, whichever way its being used.
 
@@ -40,7 +40,7 @@ Gicisky labels have been painted successfully using BLE Manager. Zhsunyco labels
 - [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
 
-Zhsunyco labels still have problems through BLE Manager even with these fixes, so the BLE Manager setting stays off by default for now. Direct BlueZ access remains the reliable choice for them.
+BLE Manager is now the default. If a label misbehaves through it, turn off "Use the SignalK BLE Manager API" to go back to direct BlueZ access.
 
 v2.34.0 also releases a plugin's Bluetooth connections when the plugin stops ([PR#3093](https://github.com/SignalK/signalk-server/pull/3093)). v2.35.0 stops plugins cleanly when the server shuts down or is restarted from the admin UI ([PR#3194](https://github.com/SignalK/signalk-server/pull/3194)). On a shutdown this plugin only waits 5 seconds for a label part way through a repaint, rather than the usual 30, so that it finishes inside the server's shutdown deadline.
 
@@ -68,6 +68,9 @@ Sometime Bluetooth adapters, and/or the Linux services that use them, can get in
 
 ## Zhsunyco Labels and the BLE Manager
 
+> [!NOTE]
+> ZhSunyCo labels may show as manufacturer label`WOESL`, or as a `WL` prefixed device name, on 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. This was fixed in SignalK v2.34.0, so upgrading is the first thing to try.
 
 On 2.33 and earlier, either:

package/docs/design/spec.md

@@ -9,11 +9,11 @@ A SignalK plugin, in TypeScript, that renders selected SignalK data to BLE eInk
 - Pluggable vendor support
   - Built-in drivers for Zhsunyco and Gicisky BLE labels (`src/devices/zhsunyco/`, `src/devices/gicisky/`), registered by `plugin.ts` at startup
   - Each driver has a metadata table of the models it supports, keyed by PID, with `hwVersion` used where a vendor reuses a PID across panel sizes. Each entry gives the label, width, height, vertical offset and colours. `esl-cli vendors` lists them
-  - Additional vendors are added by a separate npm package implementing `VendorDriver` and calling the exported `registerVendorDriver` explicitly - no scanning of installed packages. In the SignalK runtime the extension calls it from its own plugin `start()`; the CLI loads it via `esl-cli --require <module>`. Extension packages declare this package as a regular `dependency`, not a `peerDependency` (SignalK's guidance is that npm's peer-dependency resolution interacts poorly with the server's plugin install layout), and declare the SignalK-level relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` - see [Extending](../extending.md)
+  - Additional vendors are added by a separate npm package implementing `VendorDriver` and calling the exported `registerVendorDriver` explicitly - no scanning of installed packages. In the SignalK runtime the extension calls it from its own plugin `start()`; the CLI loads it via `esl-cli --require <module>`. Extension packages declare the relationship only via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` (plus a `devDependency` for types/tests), not as a regular `dependency` or `peerDependency` - the App Store installs it flat in `~/.signalk/node_modules`, so `require` resolves the single running copy - see [Extending](../extending.md)
   - The config schema's device and template options are read live from the registries when the schema is built, so a newly-registered extension shows up the next time the config panel is opened
 - Bluetooth access, either direct or shared
   - Direct BlueZ access over D-Bus via `node-ble` (the default). The plugin waits, with backoff, for a local adapter before scanning or painting, to cover the boot-time race where the plugin starts before BlueZ is ready
-  - The SignalK BLE Manager API (`app.bleApi`, server >= 2.32.0), opted into with `useBleApi`, so the plugin shares the adapter with other BLE plugins. Only offered in the config schema when the running server has it. Paints through BLE Manager are serialised so only one label holds a GATT connection at a time
+  - The SignalK BLE Manager API (`app.bleApi`, server >= 2.32.0), used by default (`useBleApi`, falling back to direct BlueZ access on older servers), so the plugin shares the adapter with other BLE plugins. Only offered in the config schema when the running server has it. Paints through BLE Manager are serialised so only one label holds a GATT connection at a time
 - Device discovery
   - One shared discovery path across all registered drivers (`discoveryCoordinator.ts`): each advertisement is read once and offered to each driver's `matchesAdvertisement`; only a matching driver's `identifyDevice` runs, which may open a GATT connection when the advertisement alone doesn't identify the model
   - A scan already in progress is joined rather than a second one started, since neither backend can run two discovery sessions at once
@@ -42,6 +42,7 @@ A SignalK plugin, in TypeScript, that renders selected SignalK data to BLE eInk
   - An `<image>` element with a `<desc>` binding and an `assets=<name>` key picks one `.svg` from an asset directory (`.assets/<name>/`, user templates directory first, then bundled) by the resolved value, e.g. the bundled `lunar_phases` icons for `environment.moon.phaseName`. The element is dropped when the value is missing or has no matching file
 - SignalK API base URL
   - `signalkApiUrl` is optional. Left unset, `resolveSignalkApiUrl` (`src/resolveApiUrl.ts`) probes `http://localhost:3000`, `http://localhost` and `https://localhost`, in that order, at the first repaint and caches whichever responds. Always the loopback address, since the plugin runs on the same host as the server. Setting it explicitly skips probing but is still verified
+  - `allowSelfSignedCertificates` (off by default) makes `fetchJson` (`src/httpJson.ts`) accept a self-signed certificate on these API calls, using `node:https` with verification off and following redirects itself. A server with SSL enabled redirects its http port to https, usually with its own generated certificate, which plain `fetch()` rejects. With it off, a certificate failure's error names the setting. A failure to resolve the URL is logged as an error, with each candidate's underlying cause
   - It errors clearly if nothing responds (wrong port) or every probe is rejected (anonymous read access not enabled) - these endpoints need anonymous read access, since the plugin has no login flow. A failed resolution is retried on the next repaint rather than cached
   - Path metadata is best-effort (no server just means raw values); a `category=` or `provider=` binding without a reachable server fails the render
 - Repainting

package/docs/extending.md

@@ -20,7 +20,7 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 - `import esl from '@rhizomatics/signalk-einklabel-plugin'; esl.registerVendorDriver(myDriver)`
 - In the SignalK runtime, call this from the extension's own plugin `start()`. In the CLI, load the extension with `esl-cli --require <module> <command>`.
-- Declare this package as a regular npm `dependency` in the extension package - **not** a `peerDependency`, per SignalK's own guidance that npm's peer-dependency resolution interacts poorly with the server's plugin install layout - and declare the SignalK-level relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the extension's own `package.json` instead, so the App Store can install/report it.
+- Don't list this package in the extension's `dependencies` or `peerDependencies` - declare the relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the extension's own `package.json` instead, and add it as a `devDependency` for types and tests. The App Store installs required plugins flat in `~/.signalk/node_modules`, so the extension's `require` still resolves at runtime - and always to the one copy the running plugin uses. A regular `dependency` can leave a separate nested copy under the extension (e.g. on a version mismatch), with its own empty registry, so the registration silently goes nowhere; a `peerDependency` interacts poorly with the server's plugin install layout, per SignalK's own guidance.
 
 ## Template Providers
 

package/package.json

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