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

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,25 +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,
-            mirror: device.mirror,
-            compress: device.compress,
-            compressionFormat: device.compressionFormat,
+            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,
@@ -378,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 = [];
@@ -389,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) => {
@@ -408,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) {
@@ -455,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"
+```

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).