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

package/CHANGELOG.md

@@ -1,6 +1,30 @@
 # 1.3.0
 
-First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services. Off by default until longer term stability demonstrated.
+## BLE Manager
+
+First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services.
+
+- Off by default until longer term stability demonstrated.
+- It may be less reliable for some devices that can be reached with direct bluez access - try it and fall back to the direct mode if so.
+- BLE Manager use reduces interference between plugins competing for same BLE devices
+- Recommend using SignalK at least release v2.33.0.
+
+## Compression
+
+Images are now compressed before sending - no change to what's displayed, but send time is massively reduced for labels with lots of empty space, so less battery is used and sends are less likely to fail.
+
+- 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)
+
+## Advanced Options
+
+Connect timeout and retries can now be defined per label.
+
+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).
 
 # 1.2.3
 

package/README.md

@@ -134,10 +134,16 @@ Enable the plugin, and use the large **+** sign to add a label, which opens up t
   - 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.
 
-There are also two more advanced options, which can usually be ignored.
+- _If the render doesn't match the panel size_ - see [Reframing](#reframing)
 
-- _BLE AES key_ - Only needed if the default key doesn't work and you have a better alternative, otherwise ignore
+The rest are grouped under _Advanced settings_, and can usually be ignored.
+
+- _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
+- _Paint connect timeout_ and _Paint retries_ for this device - leave blank to use the plugin-wide settings, or set them for a label that's slower to respond or further away than the others
+
+Configs saved by earlier versions are moved into this layout automatically when the plugin starts.
 
 When the plugin starts, it will automatically re-paint the label if it's new, or the last timed slot was missed and the data has changed.
 
@@ -178,6 +184,14 @@ Templates are simply SVG files, to which expressions can be added to use SignalK
 
 There's some wiggle room with the `reframe` options to use a template that's a bit too small, or too large, for the label, although best results come from a template that's precisely matching the pixel height and width of the label. Next best is template that has the same aspect ratio, so it can be cleanly scaled. `crop` is the 2nd least worst, though if its only a handful of pixels its often not worth worring about a separate template and `crop` is just fine. `scale` is likely to look worst, since it will force an image in regardless of aspect ratio.
 
+### Other Image Options
+
+Each label has a few more settings for how the image is sent, under _Advanced settings_. The CLI `paint` command has matching options (see [Command Line Interface](#command-line-interface)), so you can try them on a label before changing the plugin config.
+
+- _Compress upload_ - on by default. Sends much less data over Bluetooth, so painting is quicker, uses less of the label's battery and is less likely to time out. Works for Zhsunyco labels and Gicisky 7.5"/10.2" labels, and is ignored for others. Turn it off if a label stops updating.
+- _Wire format (Gicisky, experimental)_ - `auto` by default. `chunked` sends a Gicisky 4.2" BWR label compressed, the same way as the 7.5"/10.2". The vendor's own app has been seen doing this, but it hasn't been tested on current firmware. Set it back to `auto` if the label stops updating.
+- _Mirror_ - `none` by default. `horizontal` or `vertical` fixes a label model whose image comes out mirrored. `both` rotates the image 180°, for a label that has to be mounted upside down.
+
 ### Template Families (multiple panel sizes/colours)
 
 A "Template" selection can either be one specific `.svg` file, or a _directory_ holding several versions of the same template for different panel sizes/colour-sets, e.g. `templates/tides/416x240-BWRY.svg` and `templates/tides/250x128-BWRY.svg` both implement the tide clock, just at different sizes.
@@ -309,6 +323,12 @@ Left unset, both `render` and `paint` default `-w/--width`/`--height` to the tem
 
 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](#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 by a `-r/--require`'d package - see [Extending](#extending) below - which is how [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) adds its own `prompt`/`generate` commands for testing prompts without a device.
 
 ( 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` )
@@ -377,12 +397,24 @@ The label address previously discovered via `esl-cli scan`
 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), that's normally rejected as a mismatch - add `--reframe` to fit it instead:
+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).
@@ -537,6 +569,8 @@ USB_DENYLIST="0b05:190e"
 
 ## Other ESL and General eInk Resources
 
+### Components
+
 - [Open ePaper Link](https://openepaperlink.de) - Alternative open source firmware to flash onto eInk shelf labels, with Home Assistant integration.
 - [zhsunyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface
 - [WoLink](https://github.com/NickWaterton/Wolink) - Python interface and protocol analysis
@@ -545,9 +579,14 @@ USB_DENYLIST="0b05:190e"
 - [esp32-esl-system](https://github.com/giobauermeister/esp32-esl-system) - Docker and ESP32 based system for updating ESLs.
 - [hass-gicisky](https://github.com/eigger/hass-gicisky) - Home Assistant integration for Gicisky ESLs ( a similar vendor to Zhsunyco). Uses [imagespec](https://github.com/eigger/imagespec) for templating.
 - [ha-panda](https://github.com/moryoav/ha-panda) - Home Assistant integration for Panda ESLs ( a similar vendor to Zhsunyco).
+
+### Notes and Experiences
+
+- [Cabalist Gicisky Image Notes](https://github.com/Cabalist/gicisky_image_notes)
 - [Dmitry.gr](https://dmitry.gr/?r=05.Projects&proj=29.%20eInk%20Price%20Tags) - Personal site of an ESL hacker
 - [Aaron Christobel](https://www.youtube.com/@atc1441) - YouTube channel of an ESL hacker.
 - [rbaron.net](https://rbaron.net/blog/2022/07/29/Daisy-chaining-multiple-electronic-shelf-labels) - Blog of an early ESL hacker.
+  ### Retail
 - [Pimoroni](https://shop.pimoroni.com/collections/displays?tags=e-ink%20Displays) - All shapes and sizes of eInk displays, aimed at hackers, and with an [inky](https://github.com/pimoroni/inky) GitHub project to support them.
 - [WaveShare](https://www.waveshare.com/product/displays/e-paper.htm) - Wide range of eInk displays for hardware projects, not limited to ESLs.
 

package/dist/cli/index.d.ts

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { Colour } from "../devices/types";
+import { Colour, CompressionFormat } from "../devices/types";
 import { ReframeMode } from "../render/reframe";
+import { MirrorMode } from "../render/mirror";
 import { Binding } from "../render/binding";
 import { TemplateContext } from "../render/types";
 /** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
 export declare const DEFAULT_SIGNALK_URLS: string[];
 export declare function parseColours(code: string): Colour[];
 export declare function parseReframeMode(value: string): ReframeMode;
+export declare function parseMirrorMode(value: string): MirrorMode;
+export declare function parseCompressionFormat(value: string): CompressionFormat;
 /** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
 export declare function assembleContext(opts: {
     url?: string;

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,9 @@ exports.program
             modelOverride,
             connectTimeoutMs,
             reframe: parseReframeMode(opts.reframe),
+            mirror: parseMirrorMode(opts.mirror),
+            compress: opts.compress,
+            compressionFormat: parseCompressionFormat(opts.compressionFormat),
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
@@ -287,7 +309,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 +319,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
@@ -26,8 +27,6 @@ export interface DeviceConfig {
      * `./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,6 @@ 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;
     /**
      * 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 +55,34 @@ 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"`. */
+    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;
+    /** 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
@@ -71,6 +95,9 @@ export interface PluginConfig {
      * signalk-bluetti-plugin does. Off by default - a `device: ALL_DEVICES` entry scans on demand the
      * first time it has nothing discovered yet (see `resolveTargets` in `repaintScheduler.ts`), and an
      * explicit device selection only ever needed this to populate the dropdown once at initial setup.
+     * Also unnecessary with `useBleApi` on, which discovers continuously in the background instead (see
+     * `startBleApiDiscoveryListener` in `discoveryCoordinator.ts`) - kept meaningful mainly for direct
+     * BlueZ access, which has no continuous-scan equivalent to piggyback on.
      */
     scanOnStart: boolean;
     /** How long the startup scan runs, in seconds. */
@@ -137,16 +164,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): {

package/dist/config.js

@@ -1,9 +1,10 @@
 "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.resolveTemplatePath = resolveTemplatePath;
@@ -23,6 +24,49 @@ 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 = [
+    "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 +152,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 +348,34 @@ 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 };
+}
+/**
+ * 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();
@@ -309,6 +384,18 @@ function configSchema(app, discovered = []) {
     return {
         type: "object",
         properties: {
+            ...(app.bleApi
+                ? {
+                    useBleApi: {
+                        type: "boolean",
+                        title: "Use the SignalK BLE Manager API",
+                        description: "Route Bluetooth access through SignalK server's BLE Manager API (server >= 2.32.0) instead of connecting to " +
+                            "BlueZ directly, so this plugin shares the adapter with other BLE plugins instead of contending for it. Requires " +
+                            "the server to have a local Bluetooth adapter or BLE gateway available (Server → Settings → Bluetooth).",
+                        default: defaults.useBleApi,
+                    },
+                }
+                : {}),
             templatesDir: {
                 type: "string",
                 title: "Templates directory",
@@ -321,7 +408,8 @@ function configSchema(app, discovered = []) {
                 type: "boolean",
                 title: "Scan for devices on plugin start",
                 description: 'Runs a short BLE scan so discovered devices show up in a device\'s "Device" picker below. ' +
-                    'Not needed if every device uses "All discovered devices" - that scans on demand instead.',
+                    'Not needed if every device uses "All discovered devices" (that scans on demand instead), or if ' +
+                    '"Use BLE Manager" below is on (that discovers continuously in the background instead of needing a scan).',
                 default: defaults.scanOnStart,
             },
             scanDurationSeconds: {
@@ -331,29 +419,19 @@ function configSchema(app, discovered = []) {
                 minimum: 1,
                 default: defaults.scanDurationSeconds,
             },
-            ...(app.bleApi
-                ? {
-                    useBleApi: {
-                        type: "boolean",
-                        title: "Use the SignalK BLE Manager API",
-                        description: "Route Bluetooth access through SignalK server's BLE Manager API (server >= 2.32.0) instead of connecting to " +
-                            "BlueZ directly, so this plugin shares the adapter with other BLE plugins instead of contending for it. Requires " +
-                            "the server to have a local Bluetooth adapter or BLE gateway available (Server → Settings → Bluetooth).",
-                        default: defaults.useBleApi,
-                    },
-                }
-                : {}),
             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,
             },
@@ -394,11 +472,10 @@ function configSchema(app, discovered = []) {
                                 '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"],
-                        },
+                        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)",
@@ -415,22 +492,58 @@ function configSchema(app, discovered = []) {
                             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",
+                        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: {
+                                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.",
+                                    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.", 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" }),
+                                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 (vendor-specific; leave blank to use a default key)",
+                                },
+                                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,
+                                },
+                            },
                         },
                     },
                 },
@@ -445,6 +558,10 @@ function configUiSchema() {
                 description: { "ui:widget": "textarea" },
                 repaintTrigger: { "ui:widget": "radio" },
                 reframe: { "ui:widget": "radio" },
+                advanced: {
+                    mirror: { "ui:widget": "radio" },
+                    compressionFormat: { "ui:widget": "radio" },
+                },
             },
         },
     };