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

package/dist/config.js

@@ -7,6 +7,9 @@ exports.readCurrentConfig = readCurrentConfig;
 exports.healStoredConfig = healStoredConfig;
 exports.resolveTemplatesDir = resolveTemplatesDir;
 exports.parseDevice = parseDevice;
+exports.listSvgFiles = listSvgFiles;
+exports.listTemplateVariants = listTemplateVariants;
+exports.listTemplateFamilies = listTemplateFamilies;
 exports.resolveTemplatePath = resolveTemplatePath;
 exports.configSchema = configSchema;
 exports.configUiSchema = configUiSchema;
@@ -362,9 +365,9 @@ function withEnum(schema, values, names) {
 }
 /** The plugin's documentation site - its sections' anchors are the README's own headings (see `site/scripts/sync-readme.mjs`). */
 const DOCS_URL = "https://signalk-einklabel.rhizomatics.org.uk/";
-/** A Markdown link to a docs section, for a field description rendered with `ui:enableMarkdownInDescription` (see `configUiSchema`). */
-function docsLink(anchor, text = "More in the docs") {
-    return `[${text}](${DOCS_URL}#${anchor})`;
+/** A Markdown link to a docs page (and optional section, e.g. `templates/#reframing`), for a field description rendered with `ui:enableMarkdownInDescription` (see `configUiSchema`). */
+function docsLink(page, text = "More in the docs") {
+    return `[${text}](${DOCS_URL}${page})`;
 }
 /**
  * An enum-like string field whose options show explanatory labels rather than their raw stored values
@@ -481,12 +484,12 @@ function configSchema(app, discovered = []) {
                             title: "Location/description (optional)",
                             description: 'Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m ' +
                                 'in poor light" - available to any template as `source=label,path=description`. ' +
-                                docsLink("label-details"),
+                                docsLink("templates/#label-details"),
                         },
                         templateName: withEnum({
                             type: "string",
                             title: "Template",
-                            description: `A bundled template, or one from your templates directory. ${docsLink("templating")}`,
+                            description: `A bundled template, or one from your templates directory. ${docsLink("examples/")}`,
                         }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
                         repaintTrigger: choiceField("Repaint trigger", [
                             ["subscription", "When a SignalK path changes"],
@@ -501,11 +504,11 @@ function configSchema(app, discovered = []) {
                                     ["crop", "Crop - place at the top-left, cutting off anything too big or leaving the rest blank"],
                                     ["scale", "Scale - stretch to fit exactly (may distort)"],
                                     ["fixed", "Fixed - fail the repaint rather than show an off-size image"],
-                                ], { description: docsLink("reframing"), default: "crop" }),
+                                ], { description: docsLink("templates/#reframing"), default: "crop" }),
                                 compress: {
                                     type: "boolean",
                                     title: 'Compress upload (Zhsunyco, Gicisky 7.5"/10.2")',
-                                    description: `Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating. ${docsLink("other-image-options")}`,
+                                    description: `Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating. ${docsLink("templates/#other-image-options")}`,
                                     default: true,
                                 },
                                 mirror: choiceField("Mirror", [
@@ -514,7 +517,7 @@ function configSchema(app, discovered = []) {
                                     ["vertical", "Flip top to bottom"],
                                     ["both", "Rotate 180° - for a label mounted upside down"],
                                 ], {
-                                    description: `Only needed if the image shows up mirrored or upside down on the label. ${docsLink("other-image-options")}`,
+                                    description: `Only needed if the image shows up mirrored or upside down on the label. ${docsLink("templates/#other-image-options")}`,
                                     default: "none",
                                 }),
                                 compressionFormat: choiceField("Wire format (Gicisky, experimental)", [
@@ -524,7 +527,7 @@ function configSchema(app, discovered = []) {
                                         'Chunked - send compressed like the 7.5"/10.2" panels, e.g. to speed up a 4.2" BWR (untested on current firmware)',
                                     ],
                                 ], {
-                                    description: `Chunked needs Compress upload on. Switch back to Auto if the label stops updating. ${docsLink("other-image-options")}`,
+                                    description: `Chunked needs Compress upload on. Switch back to Auto if the label stops updating. ${docsLink("templates/#other-image-options")}`,
                                     default: "auto",
                                 }),
                                 forceRepaint: {
@@ -616,7 +619,7 @@ function configUiSchema() {
                     "advanced",
                 ],
                 friendlyName: { "ui:placeholder": "e.g. Tide clock" },
-                description: { "ui:widget": "textarea", "ui:placeholder": "e.g. chart table, viewed from about 1m in poor light", ...MARKDOWN },
+                description: { "ui:widget": "textarea", "ui:placeholder": "e.g. at companionway", ...MARKDOWN },
                 templateName: MARKDOWN,
                 repaintTrigger: { "ui:widget": "radio" },
                 triggerPath: { "ui:placeholder": "e.g. environment.tide.state" },

package/dist/docs/templateReference.d.ts

@@ -0,0 +1,18 @@
+/** The reference block for one bundled template name, e.g. `tides` (a family) or `tide.svg`. */
+export declare function templateReference(templateName: string, templatesDir?: string): string;
+/** Every bundled template name a user can pick - plain `.svg` files and family directories, not dot-prefixed internals. */
+export declare function bundledTemplateNames(templatesDir?: string): string[];
+/** A one-row-per-template summary, linking each to the example page whose reference block covers it. */
+export declare function templatesSummary(pagesByTemplate: Map<string, string>, templatesDir?: string): string;
+/**
+ * Regenerates every marked block under `examplesDir`, returning each file's current and regenerated
+ * content. `templates-summary` blocks link to whichever page holds a template's `template-reference`
+ * block, so all pages are scanned for those first.
+ */
+export declare function regenerateExampleDocs(examplesDir: string, templatesDir?: string): {
+    path: string;
+    current: string;
+    updated: string;
+    stale: boolean;
+}[];
+export declare const EXAMPLES_DOCS_DIR: string;

package/dist/docs/templateReference.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXAMPLES_DOCS_DIR = void 0;
+exports.templateReference = templateReference;
+exports.bundledTemplateNames = bundledTemplateNames;
+exports.templatesSummary = templatesSummary;
+exports.regenerateExampleDocs = regenerateExampleDocs;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const binding_1 = require("../render/binding");
+const config_1 = require("../config");
+const zhsunyco_1 = require("../devices/zhsunyco");
+const gicisky_1 = require("../devices/gicisky");
+/**
+ * Generates the "Template reference" blocks in the docs' example pages from the bundled templates
+ * themselves - sizes, aspect ratios, colours, which supported labels each size fits, and the data
+ * fields each one reads - so that reference can't drift from the templates it describes. Blocks sit
+ * between `<!-- BEGIN GENERATED: <kind> [<template>] -->` and `<!-- END GENERATED -->` markers in
+ * hand-written pages; everything outside them is left alone. Run `npm run docs:templates` to update,
+ * and `templateReference.test.ts` fails when a block is stale.
+ */
+const TEMPLATE_SOURCE_URL = "https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates";
+const MARKER = /<!-- BEGIN GENERATED: ([\w-]+)(?: ([^\s>]+))? -->[\s\S]*?<!-- END GENERATED -->/g;
+const COLOUR_LETTER = { black: "B", white: "W", red: "R", yellow: "Y" };
+function supportedLabels() {
+    return [new zhsunyco_1.ZhsunycoDriver(), new gicisky_1.GiciskyDriver()].flatMap((driver) => driver.supportedDevices());
+}
+/** Every file a bundled template name covers - one for a plain `.svg`, one per variant for a family directory. */
+function templateFiles(templatesDir, templateName) {
+    const path = (0, path_1.join)(templatesDir, templateName);
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error(`template "${templateName}" not found in ${templatesDir}`);
+    }
+    const read = (relativePath, colours) => {
+        const source = (0, fs_1.readFileSync)((0, path_1.join)(templatesDir, relativePath), "utf-8");
+        return { path: relativePath, ...(0, binding_1.readTemplateDimensions)(source), colours, bindings: (0, binding_1.findBindings)(source) };
+    };
+    if ((0, fs_1.statSync)(path).isDirectory()) {
+        return (0, config_1.listTemplateVariants)(path)
+            .sort((a, b) => b.width - a.width || b.height - a.height)
+            .map((variant) => read(`${templateName}/${variant.fileName}`, variant.colours));
+    }
+    return [read(templateName)];
+}
+function variantName(file) {
+    return file.path
+        .split("/")
+        .pop()
+        .replace(/\.svg$/, "");
+}
+function aspectRatio(width, height) {
+    return `${(width / height).toFixed(2)} : 1`;
+}
+function matchingLabels(file, labels) {
+    const matches = labels
+        .filter((label) => label.width === file.width && label.height - label.voffset === file.height)
+        .map((label) => {
+        const colours = label.colours.map((colour) => COLOUR_LETTER[colour]).join("");
+        // Some models' own label already names their colours (e.g. Gicisky's `2.9" BWR`).
+        const name = label.label.includes(colours) ? label.label : `${label.label} ${colours}`;
+        return `${label.manufacturer ?? ""} ${name}`.trim();
+    });
+    return matches.length > 0 ? [...new Set(matches)].join(", ") : "none exactly - see [Reframing](../templates.md#reframing)";
+}
+function describeSource(binding) {
+    switch (binding.source) {
+        case "signalk":
+            return binding.context === "self" ? "Signal K path" : `Signal K path (${binding.context})`;
+        case "resources":
+            return `\`${binding.resource}\` resource${binding.provider ? ` (provider \`${binding.provider}\`)` : ""}`;
+        case "einklabel":
+            return "Plugin";
+        case "label":
+            return "Label details";
+    }
+}
+function describeOptions(binding) {
+    return [
+        binding.assets && `image from \`${binding.assets}\``,
+        binding.format && `format \`${binding.format}\``,
+        binding.category && `category \`${binding.category}\``,
+        binding.round !== undefined && `round ${binding.round}`,
+        binding.default !== undefined && `default \`${binding.default}\``,
+    ].filter((option) => Boolean(option));
+}
+/** A table row per distinct field - array indexes collapsed, so `extremes[0].time` and `extremes[2].time` are one row. */
+function fieldsTable(files) {
+    const rows = new Map();
+    for (const file of files) {
+        for (const binding of file.bindings) {
+            const source = describeSource(binding);
+            const path = binding.path.replace(/\[\d+\]/g, "[n]");
+            const key = `${source}\u0000${path}`;
+            const row = rows.get(key) ?? { source, path, options: new Set(), usedIn: new Set() };
+            describeOptions(binding).forEach((option) => row.options.add(option));
+            row.usedIn.add(variantName(file));
+            rows.set(key, row);
+        }
+    }
+    const showUsedIn = files.length > 1;
+    const header = showUsedIn ? "| Source | Path | Options | Used in |\n|---|---|---|---|" : "| Source | Path | Options |\n|---|---|---|";
+    const sorted = [...rows.values()].sort((a, b) => a.source.localeCompare(b.source) || a.path.localeCompare(b.path));
+    const lines = sorted.map((row) => {
+        const usedIn = row.usedIn.size === files.length ? "all" : [...row.usedIn].join(", ");
+        const cells = [row.source, `\`${row.path}\``, [...row.options].join(", ") || "-", ...(showUsedIn ? [usedIn] : [])];
+        return `| ${cells.join(" | ")} |`;
+    });
+    return [header, ...lines].join("\n");
+}
+/** The reference block for one bundled template name, e.g. `tides` (a family) or `tide.svg`. */
+function templateReference(templateName, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const files = templateFiles(templatesDir, templateName);
+    const labels = supportedLabels();
+    const sizes = files.map((file) => {
+        const size = file.width && file.height ? `${file.width} × ${file.height}` : "-";
+        const ratio = file.width && file.height ? aspectRatio(file.width, file.height) : "-";
+        const colours = file.colours?.join(", ") ?? "-";
+        return `| [\`${file.path}\`](${TEMPLATE_SOURCE_URL}/${file.path}) | ${size} | ${ratio} | ${colours} | ${matchingLabels(file, labels)} |`;
+    });
+    return [
+        `**Template:** \`${templateName}\``,
+        "",
+        "| File | Size (px) | Aspect ratio | Colours | Fits these labels exactly |",
+        "|---|---|---|---|---|",
+        ...sizes,
+        "",
+        "**Data used**",
+        "",
+        fieldsTable(files),
+    ].join("\n");
+}
+/** Every bundled template name a user can pick - plain `.svg` files and family directories, not dot-prefixed internals. */
+function bundledTemplateNames(templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    return [...(0, config_1.listTemplateFamilies)(templatesDir), ...(0, config_1.listSvgFiles)(templatesDir)].sort();
+}
+/** A one-row-per-template summary, linking each to the example page whose reference block covers it. */
+function templatesSummary(pagesByTemplate, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const rows = bundledTemplateNames(templatesDir).map((name) => {
+        const files = templateFiles(templatesDir, name);
+        const sizes = files.map((file) => (file.width && file.height ? `${file.width}×${file.height}` : "?")).join(", ");
+        // Only what has to come from outside the plugin - its own and the label's details are always there.
+        const external = files
+            .flatMap((file) => file.bindings)
+            .filter((binding) => binding.source === "signalk" || binding.source === "resources");
+        const resources = external.filter((binding) => binding.source === "resources").map(describeSource);
+        const paths = external.filter((binding) => binding.source === "signalk").map((binding) => `\`${binding.path}\``);
+        const sources = [...new Set(resources), ...(paths.length > 0 ? [`Signal K ${[...new Set(paths)].sort().join(", ")}`] : [])];
+        const page = pagesByTemplate.get(name);
+        return `| ${page ? `[\`${name}\`](${page})` : `\`${name}\``} | ${sizes} | ${sources.join(", ") || "-"} |`;
+    });
+    return ["| Template | Sizes | Data needed |", "|---|---|---|", ...rows].join("\n");
+}
+function markdownFiles(dir) {
+    return (0, fs_1.readdirSync)(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = (0, path_1.join)(dir, entry.name);
+        if (entry.isDirectory())
+            return markdownFiles(path);
+        return entry.name.endsWith(".md") ? [path] : [];
+    });
+}
+/**
+ * Regenerates every marked block under `examplesDir`, returning each file's current and regenerated
+ * content. `templates-summary` blocks link to whichever page holds a template's `template-reference`
+ * block, so all pages are scanned for those first.
+ */
+function regenerateExampleDocs(examplesDir, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const pages = markdownFiles(examplesDir).map((path) => ({ path, current: (0, fs_1.readFileSync)(path, "utf-8") }));
+    const pagesByTemplate = new Map();
+    for (const page of pages) {
+        for (const match of page.current.matchAll(MARKER)) {
+            if (match[1] === "template-reference" && match[2]) {
+                pagesByTemplate.set(match[2], page.path.slice(examplesDir.length + 1));
+            }
+        }
+    }
+    return pages.map((page) => {
+        const updated = page.current.replace(MARKER, (_block, kind, arg) => {
+            const body = kind === "template-reference" && arg
+                ? templateReference(arg, templatesDir)
+                : kind === "templates-summary"
+                    ? templatesSummary(pagesByTemplate, templatesDir)
+                    : undefined;
+            if (body === undefined)
+                throw new Error(`${page.path}: unknown generated block "${kind}${arg ? ` ${arg}` : ""}"`);
+            return `<!-- BEGIN GENERATED: ${kind}${arg ? ` ${arg}` : ""} -->\n<!-- Generated from the bundled templates by \`npm run docs:templates\` - do not edit by hand. -->\n\n${body}\n\n<!-- END GENERATED -->`;
+        });
+        return { ...page, updated, stale: ignoringTableAlignment(updated) !== ignoringTableAlignment(page.current) };
+    });
+}
+/**
+ * The formatter (`oxfmt`, run by `npm run docs:templates` after this) pads Markdown table columns to
+ * line up, which this generator doesn't - so compare with that padding stripped, or a freshly
+ * formatted page would always look stale.
+ */
+function ignoringTableAlignment(markdown) {
+    return markdown
+        .split("\n")
+        .map((line) => (line.startsWith("|") ? line.replace(/\s*\|\s*/g, "|").replace(/-{3,}/g, "---") : line))
+        .join("\n");
+}
+exports.EXAMPLES_DOCS_DIR = (0, path_1.join)(__dirname, "..", "..", "docs", "examples");
+if (require.main === module) {
+    const changed = regenerateExampleDocs(exports.EXAMPLES_DOCS_DIR).filter((page) => page.stale);
+    for (const page of changed)
+        (0, fs_1.writeFileSync)(page.path, page.updated);
+    console.log(changed.length > 0 ? `updated ${changed.map((page) => page.path).join(", ")}` : "template docs already up to date");
+}

package/docs/bluetooth.md

@@ -0,0 +1,109 @@
+# Bluetooth
+
+Advice for getting a reliable Bluetooth Low Energy (BLE) connection between the SignalK server and your labels.
+
+Most of this applies to direct BlueZ mode only. If the "Use the SignalK BLE Manager API" setting is enabled, the adapter and its lifecycle are managed by the SignalK server, under its own Bluetooth admin settings, once for every BLE-consuming plugin.
+
+## Choosing a Bluetooth Adapter
+
+Only needed in direct BlueZ mode - in BLE Manager mode the adapter is whatever the SignalK server's own Bluetooth settings provide.
+
+- 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
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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
+```
+
+This happens when USB autosuspend cycles the dongle in and out of low-power suspend while idle. When bluetoothd sends an HCI command while the device is suspended or mid-resume, it never gets answered — adapters like the popular ASUS USB-500 lack a GPIO to allow reset and its stuck, and spams logs.
+
+### 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"
+```

package/docs/cli.md

@@ -0,0 +1,131 @@
+# Command Line Interface
+
+To get fast feedback on templates and shelf devices without updating and configuring SignalK, a CLI call `esl-cli` is provided when the module is manually installed (see [Using Outside of SignalK](getting-started.md#using-outside-of-signalk)) that has these commands. Use `--help` to get all the options.
+
+- `vendors` - list supported vendors
+- `scan` - report supported devices found from a BLE scan
+- `render` - transform an SVG template and data into a PNG
+- `paint` - render an SVG template and data to a selected ESL
+- `fields` and `field` - see [Debugging Templates](#debugging-templates)
+
+The width, height, vertical offset and colour palette for the device are taken from the internal register of devices, however can be overridden on the command line with `-w/--width`, `--height`, `--voffset` and `--colours`. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
+
+Left unset, both `render` and `paint` default `-w/--width`/`--height` to the template's own declared `width`/`height` (or `viewBox`) - neither command connects to a device just to size the render, since that would mean an extra BLE connect ahead of `paint`'s own, and doing two back-to-back is exactly the kind of churn that trips real BLE hardware.
+
+`paint` also takes `--reframe <mode>`, applied once it has connected and identified the device, for when the rendered image doesn't come out the same size as its actual panel (see [Reframing](templates.md#reframing)):
+
+- `crop` (default) - keeps pixels 1:1, placed from the top-left; a bigger render is truncated to fit, a smaller one leaves the extra panel space blank
+- `scale` - stretches the rendered image onto the panel's exact dimensions (independently per axis, not preserving aspect ratio)
+- `fixed` - no adjustment; rejects a size mismatch with an error instead
+
+The main SignalK plugin offers the same choice per device (defaulting to `crop` there too) in each device's own config - "If the render doesn't match the panel size".
+
+`paint` has matching options for the other per-label image settings too (see [Other Image Options](templates.md#other-image-options)):
+
+- `--mirror <mode>` - `none` (default), `horizontal`, `vertical`, or `both` (rotate 180°). `render` also takes `--mirror`, to preview the flip as a PNG without a label
+- `--no-compress` - send the image uncompressed, to rule compression out if a label won't update
+- `--compression-format <format>` - `auto` (default) or `chunked`, to try the experimental compressed format on a Gicisky 4.2" BWR
+
+`esl-cli` can also be extended with new subcommands - see [Extending](extending.md#cli-commands).
+
+( The CLI can also be run from a checked out module, or by opening a terminal shell at `~/.signalk/node_modules/@rhizomatics/signalk-einklabel-plugin`, as `npx esl-cli command --args` )
+
+## Scans from CLI
+
+The command line tools, run from inside the `.signalk` directory, can be used to help troubleshoot
+
+- Scan for longer, in this example 90 seconds
+  - `npx esl-cli scan -d 90`
+- Scan for all BLE devices, whatever they are
+  - `npx esl-cli scan -a`
+
+## Debugging Templates
+
+The `esl-cli` can be used to debug and validate templates quickly:
+
+- `render` - Render templates with SignalK data and write to a local PNG file
+- `paint` - Render templates with SignalK data and send to selected ESL device
+- `fields` - List the fields in the template, with the source specification and the rendered data value
+- `field` - Accept a source specification (outside of any template context) and return the rendered value if available
+
+Use `--help` to get the full set of arguments for any of the commands.
+
+## CLI Examples
+
+### Paint Image Directly
+
+The label address previously discovered via `esl-cli scan`
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93
+```
+
+If the label turns out to be a different size than the template (e.g. it's a 250x128 template on a 416x240 panel), it's cropped to fit by default - add `--reframe scale` to stretch it instead:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --reframe scale
+```
+
+If a label doesn't update, try sending it uncompressed to see whether compression is the cause:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --no-compress
+```
+
+If the image comes out mirrored, try each `--mirror` mode until it looks right, then set the same _Mirror_ option in the label's config:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --mirror horizontal
+```
+
+### Test Template Without Updating Label
+
+This will work even if you don't have a label, or even bluetooth. (The `-u` can be left out if your SignalK server running locally on default ports).
+
+```bash
+npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -u http://localhost
+```
+
+and this version will work even without a running SignalK server, using some pre-packaged example data:
+
+```bash
+npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -e examples
+```
+
+### List all Fields and Rendered Values
+
+```bash
+npx esl-cli fields -t templates/tide.svg -u http://localhost
+```
+
+```
+id                   spec                                                                                    value
+station.name         source=resources,resource=tides,provider=tides,path=station.name                        Tobermory
+source.name.         source=resources,resource=tides,provider=tides,path=station.source.name                 TICON-4
+last_repaint         source=einklabel,path=repainted,format=local_datetime_short                             30 Jun 26 00:08
+extremes.0           source=resources,resource=tides,provider=tides,path=extremes[0].label                   Low
+extremes.1           source=resources,resource=tides,provider=tides,path=extremes[1].label                   High
+extremes.2           source=resources,resource=tides,provider=tides,path=extremes[2].label                   Low
+timezoneRegion       source=einklabel,path=local_zone                                                        BST
+lat                  source=resources,resource=tides,provider=tides,path=station.datums.LAT,category=depth   0.2m
+hat                  source=resources,resource=tides,provider=tides,path=station.datums.HAT,category=depth   5.2m
+extremes.2.level     source=resources,resource=tides,provider=tides,path=extremes[2].level,category=depth    1.1m
+extremes.2.time      source=resources,resource=tides,provider=tides,path=extremes[2].time,format=local_time  13:15
+extremes.1.level     source=resources,resource=tides,provider=tides,path=extremes[1].level,category=depth    3.8m
+extremes.1.time      source=resources,resource=tides,provider=tides,path=extremes[1].time,format=local_time  07:05
+extremes.0.time      source=resources,resource=tides,provider=tides,path=extremes[0].time,format=local_time  01:21
+extremes.0.time-8    source=resources,resource=tides,provider=tides,path=extremes[0].time,format=day_mon     30 Jun
+extremes.0.time-8-5  source=resources,resource=tides,provider=tides,path=extremes[1].time,format=day_mon     30 Jun
+extremes.0.time-8-9  source=resources,resource=tides,provider=tides,path=extremes[2].time,format=day_mon     30 Jun
+extremes.0.level     source=resources,resource=tides,provider=tides,path=extremes[0].level,category=depth    1.3m
+```
+
+## Offline Working
+
+`render` and `paint` need a `--url` argument to point to the SignalK server to retrieve data. If you don't have access to one, you can use `--example-data` or `-e` to point to a directory of example data, which is bundled with the plugin or available in GitHub at [examples](https://github.com/rhizomatics/signalk-einklabel-plugin/tree/main/examples). This also allows you to write templates for resource APIs that aren't available yet.
+
+- `vessels.json` - The standard SignalK vessel paths
+- `resources/xxxx.json` - The output of the `xxxx` resources API call
+- `categories.json` - SignalK unit categories needed for `category=depth` type formatting
+
+For example, `npx esl-cli fields -t templates/tide.svg -e examples` will show all the field data that will be populated from the example API, vessel and category data in the `examples` local directory.

package/docs/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+The plugin comes with ready-made templates for these examples. Pick one as a label's _Template_ in the plugin config, or copy it into your own templates directory as a starting point - see [Templates](../templates.md).
+
+- [Tide Clock](tide-clock.md) - the next few high and low tides, with the moon phase
+- [Watch Schedule](watch-schedule.md) - who's on watch now and next
+
+## Bundled Templates
+
+Every bundled template, with its sizes and the data it needs. Each example's page lists the exact labels each size fits and every field it reads.
+
+<!-- BEGIN GENERATED: templates-summary -->
+<!-- Generated from the bundled templates by `npm run docs:templates` - do not edit by hand. -->
+
+| Template                     | Sizes                     | Data needed                                                                                                                                                                     |
+| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`tide.svg`](tide-clock.md)  | 416×240                   | `tides` resource (provider `tides`), Signal K `environment.moon.phaseName`                                                                                                      |
+| [`tides`](tide-clock.md)     | 416×240, 296×128, 250×128 | `tides` resource (provider `tides`), Signal K `environment.moon.phaseName`                                                                                                      |
+| [`watch`](watch-schedule.md) | 416×240                   | Signal K `watch.current.endTime`, `watch.current.startTime`, `watch.current.teamName`, `watch.next.endTime`, `watch.next.startTime`, `watch.next.teamName`, `watch.system.name` |
+
+<!-- END GENERATED -->
+
+## Trying Examples Without a Boat
+
+Each template can be rendered to a PNG with the CLI using the bundled example data, with no SignalK server or label needed - see [Test Template Without Updating Label](../cli.md#test-template-without-updating-label).