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

package/CHANGELOG.md

@@ -1,6 +1,34 @@
 # 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).
+
+## Dependencies
+
+- `xmldom` updated to fix security issue with markup injection
 
 # 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): {