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

package/CHANGELOG.md

@@ -16,16 +16,26 @@ Images are now compressed before sending - no change to what's displayed, but se
 - On by default for Zhsunyco labels and Gicisky 7.5"/10.2" labels; can be turned off per label, or with `--no-compress` on the CLI
 - Experimental opt-in _Wire format_ `chunked` sends a Gicisky 4.2" BWR compressed too (`--compression-format chunked` on the CLI)
 
+## Templates
+
+- Simplified use of `label` and `einklabel` as a source of template fields, now only `label` needed, though `einklabel` won't break existing templates
+
 ## Advanced Options
 
 Connect timeout and retries can now be defined per label.
 
+SignalK Base URL now accepts a free-text value
+
 Some labels may need images flipped, so a per-label _Mirror_ option can flip the image horizontally, vertically, or both (rotate 180°, for a label mounted upside down). Also available as `--mirror` on the CLI `paint` and `render` commands.
 
 Different 'chunking' options to help with new label models.
 
 All the advanced options now grouped together to make the config clearer. Note that if you roll back to a previous version you may have to re-enter these values (they are automatically moved to the new section when upgrading).
 
+## Dependencies
+
+- `xmldom` updated to fix security issue with markup injection
+
 # 1.2.3
 
 - Improved example tide template for 2.9" Gicisky, and added blank and error templates

package/README.md

@@ -129,15 +129,14 @@ Enable the plugin, and use the large **+** sign to add a label, which opens up t
 - _Friendly Name_ - Give the label any name (word or phrase) you like, for example 'Tide Clock'
 - _Device_ - Unless you have multiple labels, don't bother with pre-scanning or selecting a specific device, instead pick **"All discovered devices"** and it will paint any compatible labels it finds. If you want to pick a specific device, you'll need to wait for a device scan to complete.
 - _Template_ - Choose a built-in template, one you've added to the local templates directory, or - if a companion plugin like [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) is installed - one of its own contributed entries (shown with a suffix, e.g. "forecast (GenAI)")
-- _Location/description_ - Optional free-text notes on where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m in poor light" - available to any template as `source=einklabel,path=description` or `source=label,path=description`
+- _Location/description_ - Optional free-text notes on 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` (see [Label Details](#label-details))
 - _Repaint Trigger_- Do you want this to repaint every few hours (at a chosen minutes past hour), or when a SignalK path changes?
   - If it's a SignalK path, enter it next, for example `environment.tide.state`
   - If it's time based, enter how many hours between repaints, for example 00:00/08:00/16:00 for an 8h schedule, and if you want a specific number of minutes after the hour.
 
-- _If the render doesn't match the panel size_ - see [Reframing](#reframing)
-
 The rest are grouped under _Advanced settings_, and can usually be ignored.
 
+- _If the render doesn't match the panel size_ - see [Reframing](#reframing)
 - _Compress upload_, _Mirror_ and _Wire format_ - see [Other Image Options](#other-image-options)
 - _Force Repaint_ - Next time the label is due to be painted, update even if the data or template hasn't changed (this flag will automatically be cleared after this.)
 - _BLE AES key_ - Only needed if the default key doesn't work and you have a better alternative, otherwise ignore
@@ -226,6 +225,20 @@ For example, `source=resources,resource=tides,provider=tides,path=station.name`
 - `path=local_zone` - a short zone name (e.g. `BST`) for the same timezone used for `local_time`/`day_mon`/`local_datetime_short` (see above) - a fallback for `environment.time.timezoneRegion,format=utc_offset` on installs that never publish that path, since it needs no SignalK metadata of its own. Falls back to a plain UTC offset like `GMT+1` where the host's locale has no real abbreviation for the zone.
 - `path=plugin_version` - expose the version of the eInk Label plugin itself.
 
+#### Label Details
+
+`source=label` reads facts about the label being painted, so one template can adapt to different labels. Available paths:
+
+- `path=description` - the label's _Location/description_ setting, e.g. `source=label,path=description`
+- `path=manufacturer` - the label's maker, e.g. `Zhsunyco`
+- `path=label` - the model's panel size, e.g. `3.7"`
+- `path=width` and `path=height` - the panel size in pixels
+- `path=colours` - the colours the panel can show, e.g. `black (#000000)`; add `format=csv` for a plain comma-separated list
+- `path=fonts` - the font families that are always available: `serif`, `sans-serif` and `monospace`
+- `path=position` - the vessel's position, rounded to about 1km
+
+These also work in the fallback warning shown when a template fails to render. Changing a label's description repaints it.
+
 #### Customizing Output
 
 A `format` can be specified to make the value easier to understand. The supported formats are:

package/dist/config.d.ts

@@ -22,7 +22,7 @@ export interface DeviceConfig {
     /**
      * Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table,
      * viewed from ~1m in poor light" - purely descriptive. Available to any template via
-     * `source=einklabel,path=description` or `source=label,path=description` (see `buildLabelContext` in
+     * `source=label,path=description` (see `buildLabelContext` in
      * `./render/binding.ts`) if it wants it - e.g. useful to a `TemplateProvider` extension (see
      * `./render/templateProviders.ts`) tailoring content to where the label actually sits.
      */
@@ -47,6 +47,10 @@ export interface DeviceConfig {
     intervalHours?: number;
     /** ...at this minute past the hour. */
     intervalMinute?: number;
+    /** Settings most labels never need, grouped so the admin UI shows them in their own "Advanced settings" box. */
+    advanced?: AdvancedDeviceSettings;
+}
+export interface AdvancedDeviceSettings {
     /**
      * How to fit the rendered image onto the device's actual panel size when it doesn't match (see
      * `ReframeMode`) - e.g. a template family with no variant sized for this particular label. Left
@@ -55,10 +59,6 @@ export interface DeviceConfig {
      * showing *something*, even off-size, beats a repaint that just fails outright.
      */
     reframe?: ReframeMode;
-    /** Settings most labels never need, grouped so the admin UI shows them in their own "Advanced settings" box. */
-    advanced?: AdvancedDeviceSettings;
-}
-export interface AdvancedDeviceSettings {
     /** Compress the upload (zhsunyco, and gicisky's chunked 7.5"/10.2" panels - ignored otherwise). Unset means on; turn off if a device fails to show compressed images. */
     compress?: boolean;
     /** Flip the image before sending - for a panel whose layout is mirrored, or one mounted upside down (`"both"`). Unset means `"none"`. */

package/dist/config.js

@@ -29,6 +29,7 @@ exports.ALL_DEVICES = "ALL";
  * saved before they were grouped still has them there. See `migrateDeviceConfig`.
  */
 const ADVANCED_DEVICE_KEYS = [
+    "reframe",
     "compress",
     "mirror",
     "compressionFormat",
@@ -359,6 +360,12 @@ function withEnum(schema, values, names) {
         return schema;
     return names ? { ...schema, oneOf: values.map((value, i) => ({ const: value, title: names[i] ?? value })) } : { ...schema, enum: values };
 }
+/** 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})`;
+}
 /**
  * An enum-like string field whose options show explanatory labels rather than their raw stored values
  * - `oneOf` with `const`/`title`, which RJSF 5 (the admin UI's form library) renders as each option's
@@ -447,8 +454,12 @@ function configSchema(app, discovered = []) {
             signalkApiUrl: {
                 type: "string",
                 title: "SignalK API base URL (leave blank to auto-detect)",
-                description: "Used for plugin access to SignalK REST APIs not yet integrated for direct plugin access. Left blank, the plugin probes the likely options at startup (3000, 80, 443 ) - only set this manually to skip probing. Anonymous read access is required.",
-                enum: ["", ...resolveApiUrl_1.SIGNALK_API_URL_OPTIONS],
+                description: "Used for plugin access to SignalK REST APIs not yet integrated for direct plugin access. Left blank, the plugin probes the likely options at startup (3000, 80, 443) - " +
+                    "only set this to skip probing, or for a server on another port or host, e.g. http://localhost:3001. Anonymous read access is required.",
+                // Free text with the probed options as suggestions - `examples` renders as the input's
+                // autocomplete list in the admin UI's form library (RJSF 5), where `enum` would forbid anything else.
+                examples: resolveApiUrl_1.SIGNALK_API_URL_OPTIONS,
+                pattern: "^(\\s*|\\s*https?://\\S+\\s*)$",
             },
             devices: {
                 type: "array",
@@ -469,43 +480,32 @@ function configSchema(app, discovered = []) {
                             type: "string",
                             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=einklabel,path=description or source=label,path=description.',
+                                'in poor light" - available to any template as `source=label,path=description`. ' +
+                                docsLink("label-details"),
                         },
-                        templateName: withEnum({ type: "string", title: "Template" }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
+                        templateName: withEnum({
+                            type: "string",
+                            title: "Template",
+                            description: `A bundled template, or one from your templates directory. ${docsLink("templating")}`,
+                        }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
                         repaintTrigger: choiceField("Repaint trigger", [
                             ["subscription", "When a SignalK path changes"],
                             ["interval", "On a timed schedule"],
                         ]),
-                        triggerPath: {
-                            type: "string",
-                            title: "Trigger SignalK path (if repaint trigger is subscription)",
-                        },
-                        intervalHours: {
-                            type: "number",
-                            title: "Repaint every N hours (if repaint trigger is interval)",
-                            minimum: 1,
-                        },
-                        intervalMinute: {
-                            type: "number",
-                            title: "Minutes past the hour (if repaint trigger is interval)",
-                            minimum: 0,
-                            maximum: 59,
-                            default: 0,
-                        },
-                        reframe: choiceField("If the render doesn't match the panel size", [
-                            ["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"],
-                        ], { default: "crop" }),
                         advanced: {
                             type: "object",
                             title: "Advanced settings",
                             description: "Most labels never need these.",
                             properties: {
+                                reframe: choiceField("If the render doesn't match the panel size", [
+                                    ["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" }),
                                 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.",
+                                    description: `Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating. ${docsLink("other-image-options")}`,
                                     default: true,
                                 },
                                 mirror: choiceField("Mirror", [
@@ -513,14 +513,20 @@ function configSchema(app, discovered = []) {
                                     ["horizontal", "Flip left to right"],
                                     ["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.", default: "none" }),
+                                ], {
+                                    description: `Only needed if the image shows up mirrored or upside down on the label. ${docsLink("other-image-options")}`,
+                                    default: "none",
+                                }),
                                 compressionFormat: choiceField("Wire format (Gicisky, experimental)", [
                                     ["auto", "Auto - the model's usual format"],
                                     [
                                         "chunked",
                                         '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.", default: "auto" }),
+                                ], {
+                                    description: `Chunked needs Compress upload on. Switch back to Auto if the label stops updating. ${docsLink("other-image-options")}`,
+                                    default: "auto",
+                                }),
                                 forceRepaint: {
                                     type: "boolean",
                                     title: "Force repaint",
@@ -529,7 +535,9 @@ function configSchema(app, discovered = []) {
                                 },
                                 aesKey: {
                                     type: "string",
-                                    title: "BLE AES key (vendor-specific; leave blank to use a default key)",
+                                    title: "BLE AES key (Zhsunyco)",
+                                    description: "32 hex characters. Leave blank to use the default key, which works for most labels.",
+                                    pattern: "^([0-9a-fA-F]{32})?$",
                                 },
                                 paintConnectTimeoutSeconds: {
                                     type: "number",
@@ -546,21 +554,78 @@ function configSchema(app, discovered = []) {
                             },
                         },
                     },
+                    // Shows only the fields for the chosen trigger. RJSF keeps a hidden field's value, so switching
+                    // trigger and back doesn't lose it - and the scheduler only reads the ones matching the trigger.
+                    dependencies: {
+                        repaintTrigger: {
+                            oneOf: [
+                                {
+                                    properties: {
+                                        repaintTrigger: { const: "subscription" },
+                                        triggerPath: {
+                                            type: "string",
+                                            title: "Trigger SignalK path",
+                                            description: "Repaints whenever this path's value changes.",
+                                        },
+                                    },
+                                },
+                                {
+                                    properties: {
+                                        repaintTrigger: { const: "interval" },
+                                        intervalHours: {
+                                            type: "number",
+                                            title: "Repaint every N hours",
+                                            minimum: 1,
+                                        },
+                                        intervalMinute: {
+                                            type: "number",
+                                            title: "Minutes past the hour",
+                                            minimum: 0,
+                                            maximum: 59,
+                                            default: 0,
+                                        },
+                                    },
+                                },
+                            ],
+                        },
+                    },
                 },
             },
         },
     };
 }
+/** Lets a field's `description` include Markdown - used for its `docsLink`. */
+const MARKDOWN = { "ui:enableMarkdownInDescription": true };
 function configUiSchema() {
     return {
+        signalkApiUrl: { "ui:placeholder": "Auto-detect, or e.g. http://localhost:3001" },
         devices: {
             items: {
-                description: { "ui:widget": "textarea" },
+                // Keeps the trigger's own fields (added by the schema's `dependencies`) next to it, rather than
+                // after every other field, and Advanced settings last.
+                "ui:order": [
+                    "friendlyName",
+                    "device",
+                    "description",
+                    "templateName",
+                    "repaintTrigger",
+                    "triggerPath",
+                    "intervalHours",
+                    "intervalMinute",
+                    "*",
+                    "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 },
+                templateName: MARKDOWN,
                 repaintTrigger: { "ui:widget": "radio" },
-                reframe: { "ui:widget": "radio" },
+                triggerPath: { "ui:placeholder": "e.g. environment.tide.state" },
                 advanced: {
-                    mirror: { "ui:widget": "radio" },
-                    compressionFormat: { "ui:widget": "radio" },
+                    reframe: { "ui:widget": "radio", ...MARKDOWN },
+                    compress: MARKDOWN,
+                    mirror: { "ui:widget": "radio", ...MARKDOWN },
+                    compressionFormat: { "ui:widget": "radio", ...MARKDOWN },
+                    aesKey: { "ui:placeholder": "e.g. 00112233445566778899aabbccddeeff" },
                 },
             },
         },

package/dist/repaintScheduler.js

@@ -260,6 +260,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 +298,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
@@ -320,6 +322,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 ?? "",
             },
         };
@@ -344,7 +347,10 @@ 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 = (device.advanced?.paintConnectTimeoutSeconds ?? config.paintConnectTimeoutSeconds) * 1000;
     const gattBackend = config.useBleApi && app.bleApi ? (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME) : undefined;
@@ -357,7 +363,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             pid: target.pid,
             aesKey: device.advanced?.aesKey,
             connectTimeoutMs,
-            reframe: device.reframe,
+            reframe: device.advanced?.reframe,
             mirror: device.advanced?.mirror,
             compress: device.advanced?.compress,
             compressionFormat: device.advanced?.compressionFormat,

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/package.json

@@ -1,20 +1,26 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.0-beta10",
+  "version": "1.3.0-beta12",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",
     "display",
+    "e-ink",
+    "e-paper",
     "eink",
+    "epaper",
     "esl",
     "gicisky",
     "instrument",
+    "marine",
+    "shelf-label",
     "signalk",
     "signalk-category-hardware",
     "signalk-category-instruments",
     "signalk-node-server-plugin",
     "tides",
     "watch-schedule",
+    "wolink",
     "zhsunyco"
   ],
   "homepage": "https://signalk-einklabel.rhizomatics.org.uk/",
@@ -56,7 +62,7 @@
     "@fontsource/roboto-serif": "^5.3.0",
     "@naugehyde/node-ble": "^1.13.5",
     "@resvg/resvg-wasm": "^2.6.2",
-    "@xmldom/xmldom": "^0.9.10",
+    "@xmldom/xmldom": "^0.9.12",
     "commander": "^15.0.0",
     "form-data": "^4.0.6",
     "luxon": "^3.7.2",
@@ -65,11 +71,11 @@
   },
   "devDependencies": {
     "@signalk/server-api": "^2.32.0",
-    "@types/luxon": "^3.7.1",
-    "@types/node": "^26.4.0",
+    "@types/luxon": "^3.7.5",
+    "@types/node": "^26.6.0",
     "@types/pngjs": "^6.0.5",
-    "oxfmt": "^0.66.0",
-    "oxlint": "^1.81.0",
+    "oxfmt": "^0.70.0",
+    "oxlint": "^1.85.0",
     "oxlint-tsgolint": "^7.0.2001",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.0"
@@ -87,9 +93,9 @@
       "docs/assets/screenshots/label_config.png"
     ],
     "recommends": [
+      "@rhizomatics/signalk-einklabel-genai-plugin",
       "signalk-watch-schedule",
-      "signalk-tides",
-      "@rhizomatics/signalk-einklabel-genai-plugin"
+      "signalk-tides"
     ]
   }
 }