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

package/dist/cli/index.js

@@ -4,6 +4,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.program = exports.DEFAULT_SIGNALK_URLS = void 0;
 exports.parseColours = parseColours;
 exports.parseReframeMode = parseReframeMode;
+exports.parseMirrorMode = parseMirrorMode;
+exports.parseCompressionFormat = parseCompressionFormat;
 exports.assembleContext = assembleContext;
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
@@ -13,6 +15,8 @@ const registry_1 = require("../devices/registry");
 const zhsunyco_1 = require("../devices/zhsunyco");
 const gicisky_1 = require("../devices/gicisky");
 const bleDiscovery_1 = require("../devices/bleDiscovery");
+const types_1 = require("../devices/types");
+const mirror_1 = require("../render/mirror");
 const svgRenderer_1 = require("../render/svgRenderer");
 const png_1 = require("../render/png");
 const binding_1 = require("../render/binding");
@@ -45,6 +49,18 @@ function parseReframeMode(value) {
     }
     return value;
 }
+function parseMirrorMode(value) {
+    if (!mirror_1.MIRROR_MODES.includes(value)) {
+        throw new Error(`unknown --mirror value "${value}" - expected one of ${mirror_1.MIRROR_MODES.join(", ")}`);
+    }
+    return value;
+}
+function parseCompressionFormat(value) {
+    if (!types_1.COMPRESSION_FORMATS.includes(value)) {
+        throw new Error(`unknown --compression-format value "${value}" - expected one of ${types_1.COMPRESSION_FORMATS.join(", ")}`);
+    }
+    return value;
+}
 /** Probes DEFAULT_SIGNALK_URLS in order and returns the first that answers a plain GET - used when -u/--url is omitted. */
 async function resolveDefaultUrl() {
     for (const candidate of exports.DEFAULT_SIGNALK_URLS) {
@@ -226,6 +242,9 @@ exports.program
     .option("--voffset <px>", "vertical pixel offset of the panel - overrides the looked-up model for unsupported hardware (requires --colours)", "0")
     .option("--colours <code>", "device colour palette for unsupported hardware: BW, BWR, or BWRY - overrides the looked-up model (uses --width/--height/--voffset)")
     .option("--reframe <mode>", "how to fit the rendered image onto the device's actual panel size when it doesn't match: crop (default - place at top-left, truncating or leaving the rest blank), scale (stretch the template to the panel), fixed (reject the mismatch instead)", "crop")
+    .option("--mirror <mode>", "flip the image before sending: none (default), horizontal, vertical, or both (rotate 180°)", "none")
+    .option("--no-compress", 'send the image uncompressed (zhsunyco; gicisky 7.5"/10.2" or --compression-format chunked - compression is on by default)')
+    .option("--compression-format <format>", 'gicisky wire format: auto (default - the model\'s usual format) or chunked (experimental - send a 4.2" BWR compressed like the 7.5"/10.2")', "auto")
     .option("--connect-timeout <seconds>", "BLE connect timeout before giving up on an attempt", "30")
     .option("--retries <n>", "number of paint attempts (including the first) before giving up", "3")
     .action(async (opts) => {
@@ -269,6 +288,10 @@ exports.program
             modelOverride,
             connectTimeoutMs,
             reframe: parseReframeMode(opts.reframe),
+            mirror: parseMirrorMode(opts.mirror),
+            compress: opts.compress,
+            compressionFormat: parseCompressionFormat(opts.compressionFormat),
+            log: log_1.logDebug,
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
@@ -287,7 +310,9 @@ exports.program
     .option("-f, --font <path>", "override a bundled font with this file (repeatable) - defaults to the bundled monospace/sans-serif/serif trio", 
 // See the -r/--require option above for why `| undefined` is needed here despite commander's typings.
 (value, previous = []) => [...previous, value])
+    .option("--mirror <mode>", "flip the PNG the same way paint --mirror would: none (default), horizontal, vertical, or both", "none")
     .action(async (opts) => {
+    const mirror = parseMirrorMode(opts.mirror);
     const svgSource = await (0, promises_1.readFile)(opts.template, "utf-8");
     const declared = (0, binding_1.readTemplateDimensions)(svgSource);
     const width = resolveDimension(opts.width, [declared.width], DEFAULT_RENDER_WIDTH);
@@ -295,7 +320,7 @@ exports.program
     const bindings = (0, binding_1.findBindings)(svgSource);
     const context = await assembleContext(opts, bindings);
     const renderer = opts.font ? new svgRenderer_1.SvgRenderer(opts.font) : new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
+    const bitmap = (0, mirror_1.mirrorBitmap)(await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR), mirror);
     await (0, promises_1.writeFile)(opts.output, (0, png_1.bitmapToPng)(bitmap));
     console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})`);
 });

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 import { ServerAPI } from "@signalk/server-api";
-import { Colour, DiscoveredDevice } from "./devices/types";
+import { Colour, CompressionFormat, DiscoveredDevice } from "./devices/types";
 import { ReframeMode } from "./render/reframe";
+import { MirrorMode } from "./render/mirror";
 /**
  * Special `device` value meaning "every currently-known discovered device" instead of one specific
  * BLE address - lets a single `DeviceConfig` entry (one template, one trigger) broadcast to every
@@ -21,13 +22,11 @@ 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.
      */
     description?: string;
-    /** Per-device override; if omitted, the vendor driver may fall back to a stock/manufacturer-default key. */
-    aesKey?: string;
     /**
      * Either one specific `.svg` file, or the name of a *template-family* directory holding several
      * same-purpose templates for different panel sizes/colour-sets, named `<width>x<height>-<colours>.svg`
@@ -48,8 +47,10 @@ export interface DeviceConfig {
     intervalHours?: number;
     /** ...at this minute past the hour. */
     intervalMinute?: number;
-    /** One-shot override to repaint even if the data is unchanged; cleared automatically once that repaint completes. */
-    forceRepaint?: boolean;
+    /** 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
@@ -58,7 +59,32 @@ export interface DeviceConfig {
      * showing *something*, even off-size, beats a repaint that just fails outright.
      */
     reframe?: ReframeMode;
+    /** 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"`. */
+    mirror?: MirrorMode;
+    /**
+     * Experimental opt-in wire format (gicisky only) - `"chunked"` sends a 4.2" BWR (or another plain
+     * two-plane panel) QuickLZ-compressed like the 7.5"/10.2". Unset means `"auto"`, the model's own
+     * format. See `CompressionFormat`.
+     */
+    compressionFormat?: CompressionFormat;
+    /** Send the image without waiting for each write to be acknowledged (zhsunyco) - see `VendorDeviceConfig.writeWithoutResponse`. Unset means off. */
+    writeWithoutResponse?: boolean;
+    /** One-shot override to repaint even if the data is unchanged; cleared automatically once that repaint completes. */
+    forceRepaint?: boolean;
+    /** Per-device override; if omitted, the vendor driver may fall back to a stock/manufacturer-default key. */
+    aesKey?: string;
+    /** Per-device override of `PluginConfig.paintConnectTimeoutSeconds` - unset uses the plugin-wide value. */
+    paintConnectTimeoutSeconds?: number;
+    /** Per-device override of `PluginConfig.paintRetries` - unset uses the plugin-wide value. */
+    paintRetries?: number;
 }
+/** Applies `migrateDeviceConfig` to every device entry - see `healStoredConfig` for persisting the result. */
+export declare function migrateConfig<T extends Partial<PluginConfig>>(config: T): {
+    config: T;
+    migrated: boolean;
+};
 export interface PluginConfig {
     /**
      * Directory the plugin scans for template files, instead of an upload UI - follows
@@ -140,16 +166,21 @@ export declare const RENDER_FALLBACK_TEMPLATE_NAME = ".error";
 export declare function defaultConfig(): PluginConfig;
 export declare function readCurrentConfig(app: ServerAPI): Partial<PluginConfig>;
 /**
- * Actively rewrites the on-disk file once it's nested (see `readCurrentConfig`'s doc comment) -
- * `readCurrentConfig` alone only self-heals in memory for callers that go through it, but the admin
- * UI's own config-editing form round-trips whatever raw JSON it was handed verbatim, including a
- * stray nested `configuration` key it never touches (no schema field maps to it) - so left alone,
- * every future save from the UI keeps re-persisting that dead weight forever (see
- * `support/signalk-einklabel-plugin.json`). Called once at plugin start, which - unlike
- * `clearForceRepaint` - isn't gated on any device having `forceRepaint` set, so a nested file gets
- * flattened even if nothing ever triggers that path.
+ * Actively rewrites the on-disk file when it's in an outdated shape - `readCurrentConfig` alone only
+ * fixes things up in memory for callers that go through it, but the admin UI's config form
+ * round-trips whatever raw JSON it was handed verbatim. Two shapes are healed:
+ *
+ * - A nested file (see `readCurrentConfig`'s doc comment): left alone, the UI keeps re-persisting a
+ *   stray nested `configuration` key it never touches (no schema field maps to it) forever (see
+ *   `support/signalk-einklabel-plugin.json`).
+ * - Advanced device settings saved before they were grouped under `advanced` (see
+ *   `migrateDeviceConfig`): left alone, the UI would show that group empty, even though the plugin
+ *   itself still honours the old values.
+ *
+ * Called once at plugin start, which - unlike `clearForceRepaint` - isn't gated on any device having
+ * `forceRepaint` set, so an outdated file gets fixed even if nothing ever triggers that path.
  */
-export declare function healNestedConfig(app: ServerAPI): void;
+export declare function healStoredConfig(app: ServerAPI): void;
 /** See `resolveDir` - `templatesDir`'s own resolution. */
 export declare function resolveTemplatesDir(templatesDir: string | undefined): string;
 export declare function parseDevice(device: string): {
@@ -158,6 +189,22 @@ export declare function parseDevice(device: string): {
     hwVersion?: string;
     address: string;
 } | undefined;
+export declare function listSvgFiles(dir: string): string[];
+export interface TemplateVariant {
+    fileName: string;
+    width: number;
+    height: number;
+    colours: Colour[];
+}
+export declare function listTemplateVariants(dir: string): TemplateVariant[];
+/**
+ * A directory only counts as a template-family option if it actually has at least one parseable
+ * variant file in it - otherwise it's something else entirely, e.g. `.assets`. Dot-prefixed
+ * directories (e.g. `.assets`, `.blank`) are always excluded, even if they happen to contain
+ * parseable variant files, since they're reserved for non-template-option use (asset bundles,
+ * work-in-progress templates not ready to appear in the dropdown, etc).
+ */
+export declare function listTemplateFamilies(dir: string): string[];
 /**
  * Resolves a template name to an actual file path - a local template overrides the bundled one of the
  * same name. `templateName` can also name a template-family *directory* (see `pickBestVariant`), in

package/dist/config.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RENDER_FALLBACK_TEMPLATE_NAME = exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
+exports.migrateConfig = migrateConfig;
 exports.defaultConfig = defaultConfig;
 exports.readCurrentConfig = readCurrentConfig;
-exports.healNestedConfig = healNestedConfig;
+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;
@@ -23,6 +27,50 @@ const resolveApiUrl_1 = require("./resolveApiUrl");
  * an on-demand scan itself if nothing's been discovered yet.
  */
 exports.ALL_DEVICES = "ALL";
+/**
+ * Every `AdvancedDeviceSettings` key - these all used to sit directly on `DeviceConfig`, so a config
+ * saved before they were grouped still has them there. See `migrateDeviceConfig`.
+ */
+const ADVANCED_DEVICE_KEYS = [
+    "reframe",
+    "compress",
+    "mirror",
+    "compressionFormat",
+    "forceRepaint",
+    "aesKey",
+    "paintConnectTimeoutSeconds",
+    "paintRetries",
+];
+/**
+ * Moves any `AdvancedDeviceSettings` key found at the top level of a device entry (the pre-grouping
+ * layout) into its `advanced` object, reporting whether anything moved. A value already under
+ * `advanced` wins over a legacy top-level one - it can only have got there from the grouped form, so
+ * it's the newer of the two.
+ */
+function migrateDeviceConfig(raw) {
+    const legacy = {};
+    const rest = { ...raw };
+    for (const key of ADVANCED_DEVICE_KEYS) {
+        if (key in rest) {
+            legacy[key] = rest[key];
+            delete rest[key];
+        }
+    }
+    if (Object.keys(legacy).length === 0) {
+        return { device: raw, migrated: false };
+    }
+    return { device: { ...rest, advanced: { ...legacy, ...raw.advanced } }, migrated: true };
+}
+/** Applies `migrateDeviceConfig` to every device entry - see `healStoredConfig` for persisting the result. */
+function migrateConfig(config) {
+    if (!Array.isArray(config.devices)) {
+        return { config, migrated: false };
+    }
+    const results = config.devices.map(migrateDeviceConfig);
+    return results.some((result) => result.migrated)
+        ? { config: { ...config, devices: results.map((result) => result.device) }, migrated: true }
+        : { config, migrated: false };
+}
 /**
  * The package's own bundled `templates/` directory (ships alongside `dist/`, see
  * package.json's `files`) - templates here are always available, but a same-named template in the
@@ -108,27 +156,33 @@ function pickKnownKeys(raw) {
 }
 function readCurrentConfig(app) {
     const { unwrapped } = unwrapNestedConfiguration(app.readPluginOptions());
-    return pickKnownKeys(unwrapped);
+    return migrateConfig(pickKnownKeys(unwrapped)).config;
 }
 /**
- * Actively rewrites the on-disk file once it's nested (see `readCurrentConfig`'s doc comment) -
- * `readCurrentConfig` alone only self-heals in memory for callers that go through it, but the admin
- * UI's own config-editing form round-trips whatever raw JSON it was handed verbatim, including a
- * stray nested `configuration` key it never touches (no schema field maps to it) - so left alone,
- * every future save from the UI keeps re-persisting that dead weight forever (see
- * `support/signalk-einklabel-plugin.json`). Called once at plugin start, which - unlike
- * `clearForceRepaint` - isn't gated on any device having `forceRepaint` set, so a nested file gets
- * flattened even if nothing ever triggers that path.
+ * Actively rewrites the on-disk file when it's in an outdated shape - `readCurrentConfig` alone only
+ * fixes things up in memory for callers that go through it, but the admin UI's config form
+ * round-trips whatever raw JSON it was handed verbatim. Two shapes are healed:
+ *
+ * - A nested file (see `readCurrentConfig`'s doc comment): left alone, the UI keeps re-persisting a
+ *   stray nested `configuration` key it never touches (no schema field maps to it) forever (see
+ *   `support/signalk-einklabel-plugin.json`).
+ * - Advanced device settings saved before they were grouped under `advanced` (see
+ *   `migrateDeviceConfig`): left alone, the UI would show that group empty, even though the plugin
+ *   itself still honours the old values.
+ *
+ * Called once at plugin start, which - unlike `clearForceRepaint` - isn't gated on any device having
+ * `forceRepaint` set, so an outdated file gets fixed even if nothing ever triggers that path.
  */
-function healNestedConfig(app) {
+function healStoredConfig(app) {
     const { unwrapped, wasNested } = unwrapNestedConfiguration(app.readPluginOptions());
-    if (!wasNested)
+    const { config, migrated } = migrateConfig(pickKnownKeys(unwrapped));
+    if (!wasNested && !migrated)
         return;
-    app.savePluginOptions(pickKnownKeys(unwrapped), (err) => {
+    app.savePluginOptions(config, (err) => {
         if (err)
-            app.debug(`failed to clean up legacy nested plugin config: ${err.message}`);
+            app.debug(`failed to update the stored plugin config: ${err.message}`);
         else
-            app.debug("cleaned up a legacy nested plugin config file on disk");
+            app.debug(`updated the stored plugin config (${[wasNested && "flattened nesting", migrated && "grouped advanced device settings"].filter(Boolean).join(", ")})`);
     });
 }
 /**
@@ -298,9 +352,40 @@ function resolveTemplatePath(templatesDir, templateName, target) {
     const localPath = (0, path_1.join)(templatesDir, templateName);
     return (0, fs_1.existsSync)(localPath) ? localPath : (0, path_1.join)(exports.BUNDLED_TEMPLATES_DIR, templateName);
 }
-/** JSON Schema forbids an empty `enum` array, so only attach one when there's at least one option - otherwise the whole config schema fails validation. */
+/**
+ * Restricts a string field to `values`, shown as `names` where given - as `oneOf` with `const`/`title`,
+ * the form RJSF 5 (the admin UI's form library) supports going forward, rather than the deprecated
+ * `enumNames`. JSON Schema forbids an empty `enum`/`oneOf` array, so neither is attached without at
+ * least one option - otherwise the whole config schema fails validation.
+ */
 function withEnum(schema, values, names) {
-    return values.length > 0 ? { ...schema, enum: values, ...(names ? { enumNames: names } : {}) } : schema;
+    if (values.length === 0)
+        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 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
+ * - `oneOf` with `const`/`title`, which RJSF 5 (the admin UI's form library) renders as each option's
+ * label while still saving the bare value, so existing configs are unaffected.
+ *
+ * Each label is prefixed with an en space: the admin UI renders RJSF's default-theme radio markup under
+ * Bootstrap 5, which has no styling for it, so the label otherwise butts straight up against its
+ * button - and a plugin can't ship its own CSS. An en space, unlike a plain one, isn't collapsed away
+ * by HTML whitespace handling.
+ */
+function choiceField(title, options, extra = {}) {
+    return {
+        type: "string",
+        title,
+        ...extra,
+        oneOf: options.map(([value, label]) => ({ const: value, title: `\u2002${label}` })),
+    };
 }
 function configSchema(app, discovered = []) {
     const defaults = defaultConfig();
@@ -347,14 +432,16 @@ function configSchema(app, discovered = []) {
             paintConnectTimeoutSeconds: {
                 type: "number",
                 title: "Paint connect timeout (seconds)",
-                description: "How long to wait for a device to accept a BLE connection before giving up on a repaint attempt.",
+                description: "How long to wait for a device to accept a BLE connection before giving up on a repaint attempt. " +
+                    "The default for every device - each device can override it in its own settings below.",
                 minimum: 1,
                 default: defaults.paintConnectTimeoutSeconds,
             },
             paintRetries: {
                 type: "number",
                 title: "Paint retries",
-                description: "How many times to attempt a repaint (including the first try) before giving up and reporting failure.",
+                description: "How many times to attempt a repaint (including the first try) before giving up and reporting failure. " +
+                    "The default for every device - each device can override it in its own settings below.",
                 minimum: 1,
                 default: defaults.paintRetries,
             },
@@ -370,8 +457,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",
@@ -392,46 +483,120 @@ 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.',
-                        },
-                        templateName: withEnum({ type: "string", title: "Template" }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
-                        repaintTrigger: {
-                            type: "string",
-                            title: "Repaint trigger",
-                            enum: ["subscription", "interval"],
+                                'in poor light" - available to any template as `source=label,path=description`. ' +
+                                docsLink("templates/#label-details"),
                         },
-                        triggerPath: {
+                        templateName: withEnum({
                             type: "string",
-                            title: "Trigger SignalK path (if repaint trigger is subscription)",
+                            title: "Template",
+                            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"],
+                            ["interval", "On a timed schedule"],
+                        ]),
+                        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("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("templates/#other-image-options")}`,
+                                    default: true,
+                                },
+                                mirror: choiceField("Mirror", [
+                                    ["none", "No flip"],
+                                    ["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. ${docsLink("templates/#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. ${docsLink("templates/#other-image-options")}`,
+                                    default: "auto",
+                                }),
+                                writeWithoutResponse: {
+                                    type: "boolean",
+                                    title: "Send image without waiting for each write (Zhsunyco)",
+                                    description: "Turn on if a Zhsunyco label fails with ATT error 0x0e when using the SignalK BLE Manager - its writes that " +
+                                        `wait for acknowledgement are rejected by these labels (SignalK 2.33 and earlier). ${docsLink("bluetooth/#zhsunyco-labels-and-the-ble-manager")}`,
+                                    default: false,
+                                },
+                                forceRepaint: {
+                                    type: "boolean",
+                                    title: "Force repaint",
+                                    description: "Repaint even if the data is unchanged - clears itself automatically once that repaint completes",
+                                    default: false,
+                                },
+                                aesKey: {
+                                    type: "string",
+                                    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",
+                                    title: "Paint connect timeout for this device (seconds)",
+                                    description: `Leave blank to use the plugin-wide setting (currently ${current.paintConnectTimeoutSeconds}s).`,
+                                    minimum: 1,
+                                },
+                                paintRetries: {
+                                    type: "number",
+                                    title: "Paint retries for this device",
+                                    description: `Leave blank to use the plugin-wide setting (currently ${current.paintRetries}).`,
+                                    minimum: 1,
+                                },
+                            },
                         },
-                        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,
-                        },
-                        aesKey: {
-                            type: "string",
-                            title: "BLE AES key (vendor-specific; leave blank to use a default key)",
-                        },
-                        forceRepaint: {
-                            type: "boolean",
-                            title: "Force repaint",
-                            description: "Repaint even if the data is unchanged - clears itself automatically once that repaint completes",
-                            default: false,
-                        },
-                        reframe: {
-                            type: "string",
-                            title: "If the render doesn't match the panel size",
-                            description: "Crop: place at the top-left, truncating anything too big or leaving the rest blank if too small. Scale: stretch to fit exactly (may distort). Fixed: fail the repaint instead of showing an off-size image.",
-                            enum: ["crop", "scale", "fixed"],
-                            default: "crop",
+                    },
+                    // 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,
+                                        },
+                                    },
+                                },
+                            ],
                         },
                     },
                 },
@@ -439,13 +604,40 @@ function configSchema(app, discovered = []) {
         },
     };
 }
+/** 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. at companionway", ...MARKDOWN },
+                templateName: MARKDOWN,
                 repaintTrigger: { "ui:widget": "radio" },
-                reframe: { "ui:widget": "radio" },
+                triggerPath: { "ui:placeholder": "e.g. environment.tide.state" },
+                advanced: {
+                    reframe: { "ui:widget": "radio", ...MARKDOWN },
+                    compress: MARKDOWN,
+                    mirror: { "ui:widget": "radio", ...MARKDOWN },
+                    compressionFormat: { "ui:widget": "radio", ...MARKDOWN },
+                    writeWithoutResponse: MARKDOWN,
+                    aesKey: { "ui:placeholder": "e.g. 00112233445566778899aabbccddeeff" },
+                },
             },
         },
     };