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

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+# 1.3.0
+
+## 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
 
 - Improved example tide template for 2.9" Gicisky, and added blank and error templates

package/README.md

@@ -24,22 +24,31 @@ Being battery operated, they can be stuck on anywhere without wiring - the only
 
 Unlike some eInk projects, this plugin doesn't require any physical modification to the labels, or loading any new firmware. It can send an image to a supported shelf label fresh out of the box.
 
-Most of requirements below are to make SignalK work with Bluetooth Low Energy, which is good thing to have anyway, since vendors like Victron, Switchbot, Ruuvi and others have BLE enabled hardware that's useful to have on a boat. [Direct BLE support](https://github.com/SignalK/signalk-server/issues/2411) in SignalK is being planned in 2026 and this plugin will support that when it comes.
+Most of requirements below are to make SignalK work with Bluetooth Low Energy, which is good thing to have anyway, since vendors like Victron, Switchbot, Ruuvi and others have BLE enabled hardware that's useful to have on a boat.
 
-1. A SignalK server, **running Linux**
+This plugin can reach BLE hardware two ways - pick whichever fits your setup:
 
-- MacOS and Windows aren't supported by the [BLE interface layer](https://www.npmjs.com/package/@naugehyde/node-ble), however they can be used for template development and
+- **Direct BlueZ access** (default) - the plugin talks to BlueZ over D-Bus itself. Requirements 1-3 below apply.
+- **SignalK BLE Manager API** (opt-in) - SignalK server >= 2.32.0 ships a [BLE Provider/Consumer API](https://github.com/SignalK/signalk-server/issues/2411) (admin UI: "BLE Manager") that arbitrates adapter access across every BLE-consuming plugin instead of each one grabbing `hci0` for itself, and can source BLE over a remote gateway instead of local hardware at all. Enable the "Use the SignalK BLE Manager API" setting in this plugin's config once it's available (it only appears once the running server has it) - requirements 1-3 below then become the SignalK server's problem, under its own Bluetooth admin settings, not this plugin's.
+
+1. A SignalK server, **running Linux** (direct BlueZ mode only - BLE Manager mode with a remote gateway provider has no such requirement)
+
+- MacOS and Windows aren't supported by the [BLE interface layer](https://www.npmjs.com/package/@naugehyde/node-ble) in direct BlueZ mode, however they can be used for template development and
   debugging (everything except `scan` and `paint`)
 
-2. A Bluetooth adapter, that can handle BLE (Bluetooth Low Energy).
+2. A Bluetooth adapter, that can handle BLE (Bluetooth Low Energy) - direct BlueZ mode only; in BLE Manager mode this is whatever the server's own Bluetooth settings provide.
 
-- Bluetooth adapters for Linux can be tricky, TP-Link UB400 and Asus USB-BT500 are two well-known and available ones
+- Bluetooth adapters for Linux can be tricky
+- TP-Link UB400 and Asus USB-BT500 are two well-known and available ones, though the ASUS USB-BT500 one can have problems with some Pi type boards
+- CSR4.0 dongles (CSR8510 chip) have had kernel support for years, and there are well known work arounds for some of them, including in the Linux kernel since v5.17
 - Some Raspberry Pi models come with suitable Bluetooth built in
+- See advice at [Recommended Bluetooth Adapters for Linux](https://github.com/morrownr/USB-WiFi/blob/main/home/Recommended_Bluetooth_Adapters_for_Linux.md)
+- Bluetooth adapters typically prefer being in USB2.0 ports rather than USB3.0 ports, since often the USB3.0 implementation leaks radio energy on the same 2.4Ghz spectrum as Bluetooth. If no USB2.0 port available, try a shielded USB2.0 extension lead to distance the dongle from the port. Some dongle manufacturees seems to do a better job at shielding for this than others.
 
 > - Don't worry about the very latest Bluetooth versions, 4.0 is minimum for BLE, 5.0 is nice
 > - Home Assistant is massively more popular than SignalK, and often also run on Raspberry Pi and similar, so good source of advice
 
-3. `bluez` package installed in Linux
+3. `bluez` package installed in Linux - direct BlueZ mode only
 
 - No need to do this if you have a Raspberry Pi with recent Raspian version, since bluez comes built in.
 - If you're not running a Raspberry Pi, then ensure that the `dbus` package is installed
@@ -82,6 +91,10 @@ Use the standard configuration option in the SignalK menu for the plugin.
 
 Template available as 416x240-BWRY for 3.7" ESLs and a simpler template, sized 250x128, also BWRY, for the cheapest 2.13" labels.
 
+This mini tide clock is a 2.9" Gicisky device, less than £10 inc delivery in summer 2026.
+
+![2.9" Tide Clock](docs/assets/images/mini_tidal_clock.png)
+
 #### Pre-requisites
 
 A _tides_ provider plugin for the Resources API installed and enabled, currently one of:
@@ -121,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.
 
@@ -165,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.
@@ -296,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` )
@@ -364,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).
@@ -461,6 +506,8 @@ That's the bundled fallback warning, not necessarily an error in this plugin - i
 
 ### SignalK starts before the Bluetooth daemon — does the plugin need `bluetoothd` running at boot?
 
+This and the next entry are about direct BlueZ mode only - if the "Use the SignalK BLE Manager API" setting is enabled, adapter/dongle lifecycle is the SignalK server's problem to manage once, for every BLE-consuming plugin, not this plugin's.
+
 The plugin retries BLE adapter initialisation with backoff (starting at 2s, capping at 30s) if `bluetoothd`/D-Bus isn't up yet when the plugin starts, so a slow-starting Bluetooth stack on boot will no longer strand it — it keeps retrying until the adapter appears rather than failing once and giving up. You'll see `BLE adapter not ready … — retrying in Ns …` in the SignalK logs in the meantime.
 
 That said, it's cleaner to fix the boot ordering at the systemd level so the plugin finds the adapter ready on its first attempt. If SignalK runs as a systemd service (`systemctl status signalk`) and its unit file has no `[Unit]` section (check with `systemctl cat signalk`), add one:
@@ -486,8 +533,44 @@ sudo systemctl restart signalk
 
 This tells systemd to start `bluetoothd` first and wait for it before starting SignalK, rather than relying on both racing to start in parallel at boot.
 
+### Bluetooth Dongle with "No gpio to reset"
+
+Example log:
+
+```
+Bluetooth: hci0: No gpio to reset Realtek device, ignoring
+Bluetooth: hci0: Unable to disable scanning: -110
+Bluetooth: hci0: command 0x2042 tx timeout
+Bluetooth: hci0: Opcode 0x2042 failed: -110
+```
+
+This happens when USB autosuspend cycles the dongle in and out of low-power suspend while idle. When bluetoothd sends an HCI command while the device is suspended or mid-resume, it never gets answered — adapters like the popular ASUS USB-500 lack a GPIO to allow reset and its stuck, and spams logs.
+
+In these examples the dongle is for vendor `0b05` and product `190e`, adapt for your own devices, use `lsusb` to find out, and if there's no `lsusb` command, install the `usbutils` package.
+
+#### Example udev rule fix
+
+Following file created at `/etc/udev/rules.d/99-bt500-no-autosuspend.rules`
+
+```
+# Disable USB autosuspend for the ASUS USB-BT500 (RTL8761BU, 0b05:190e).
+ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="0b05", ATTR{idProduct}=="190e", TEST=="power/control", ATTR{power/control}="on"
+```
+
+If `tlp` running to minimize power, it may have its own rules trying to suspend the Bluetooth dongle.
+
+#### Example tlp fix
+
+Following file created at /etc/tlp.d/99-bt500-no-autosuspend.conf
+
+```
+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
@@ -496,9 +579,14 @@ This tells systemd to start `bluetoothd` first and wait for it before starting S
 - [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) {
@@ -179,18 +195,18 @@ exports.program
         await (0, bleDiscovery_1.forEachAdvertisedDevice)(adapter, async ({ device, address, name, manufacturerId, manufacturerData }) => {
             const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
             const mfr = manufacturerId !== undefined ? `0x${manufacturerId.toString(16).padStart(4, "0")}` : "";
+            const rssi = await device
+                .getRSSI()
+                .then((value) => (value === undefined ? undefined : Number(value)))
+                .catch(() => undefined);
             if (!driver) {
                 if (opts.allDevices) {
-                    const rssi = await device
-                        .getRSSI()
-                        .then((value) => (value === undefined ? undefined : Number(value)))
-                        .catch(() => undefined);
                     rows.push(["(unmatched)", address, name ?? "", "", "", "", mfr, "", String(rssi ?? "")]);
                 }
                 return;
             }
             matchedCount++;
-            const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData);
+            const found = await driver.identifyDevice({ address, name, manufacturerId, manufacturerData, rssi }, () => (0, bleDiscovery_1.connectWithTimeout)(device, VENDOR_IDENTIFY_TIMEOUT_MS).then(() => (0, bleDiscovery_1.openNodeBleGattConnection)(device)));
             (0, log_1.logDebug)(`${driver.vendor}: identified ${found.name ?? found.address}`);
             const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, "0")}` : "";
             const hwid = found.hwVersion ? `0x${found.hwVersion}` : "";
@@ -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,10 +95,20 @@ 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. */
     scanDurationSeconds: number;
+    /**
+     * Route BLE access through the SignalK server's BLE Manager API (`app.bleApi`, 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 - see `bleBackend.ts`. Off by default, and only ever offered in the
+     * config schema when the running server actually has `app.bleApi` (see `configSchema` below).
+     */
+    useBleApi: boolean;
     /** How long to wait for a device to accept a BLE connection before giving up on a repaint attempt, in seconds. */
     paintConnectTimeoutSeconds: number;
     /** How many times to attempt a repaint (including the first try) before giving up and reporting failure. */
@@ -130,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): {