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

package/README.md

@@ -8,7 +8,7 @@
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/LICENSE)
 [![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)
 
-A SignalK plugin to display data from SignalK paths, Resource APIs and plugins on Electronic Shelf Labels (ESL) over a Bluetooth Low Energy (BLE) connection using simple SVG templates, or optionally created from a crafted prompt by GenAI if the companion [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin) is installed. Supports ESLs from two of the major Chinese manufacturers, and requires no firmware or hardware modifications, switch on and go.
+A SignalK plugin to display data from SignalK paths, Resource APIs and plugins on Electronic Shelf Labels (ESL) over a Bluetooth Low Energy (BLE) connection using simple SVG templates, or optionally created from a crafted prompt by GenAI if the companion [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin) is installed. Supports ESLs from two of the major Chinese manufacturers, and requires **no firmware or hardware modifications**, switch on and go.
 
 ![Companionway Tidal Clock](docs/assets/images/real_tidal_clock.jpg)
 
@@ -20,565 +20,23 @@ Since they are designed to be used in large quantity in small shops, they are ch
 
 Being battery operated, they can be stuck on anywhere without wiring - the only location constraints are bluetooth range, visibility (they need ambient light since the display is more like paper than a traditional lit-up electronic display) and, for some labels, being out of the weather if they are not waterproof, although IP65 labels are available.
 
-## Pre-requisites
+## Quick Start
 
-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.
+1. Check the [pre-requisites](https://signalk-einklabel.rhizomatics.org.uk/getting-started/#pre-requisites) - mainly a Linux SignalK server with a Bluetooth Low Energy adapter, or the SignalK BLE Manager API
+2. Install **eInk Label Displays** from the **SignalK AppStore** ( under _Apps & Plugins_ )
+3. In the plugin config, add a label, choose **"All discovered devices"** and a template such as the [Tide Clock](https://signalk-einklabel.rhizomatics.org.uk/examples/tide-clock/)
 
-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.
+## Documentation
 
-This plugin can reach BLE hardware two ways - pick whichever fits your setup:
+Full documentation is at [signalk-einklabel.rhizomatics.org.uk](https://signalk-einklabel.rhizomatics.org.uk):
 
-- **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) - 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, 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 - 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
-
-4. One or more supported Electronic Shelf Labels
-
-- The labels used for testing this are the [Zhsunyco 3.7" BWRY](https://www.aliexpress.com/item/1005010050104435.html) and a [Gicisky 2.9" BWRY](https://www.aliexpress.com/item/1005012933325056.html)
-
-5. Correct time zone set on server if local time is to be shown on display
-
-- See [FAQ](#faq-timezone)
-- If not set, everything will work, but you may see the wrong zone or not have daylight savings applied
-
-Once you have all of that, it may be worth also installing [signalk-victron-ble](https://github.com/stefanor/signalk-victron-ble), [signalk-ruuvitag-plugin](https://github.com/vokkim/signalk-ruuvitag-plugin) or [bt-sensors-plugin](https://github.com/naugehyde/bt-sensors-plugin-sk) to pull in data from other sensors and equipment.
-
-## Installation
-
-Look for **eInk Label Displays** in the **SignalK AppStore** on your
-server ( under _Apps & Plugins_ on the latest version).
-
-### Using Outside of SignalK
-
-The plugin can also be installed as a stand-alone module, which can be useful for designing templates away from the boat, and makes available the `esl-cli` command line tool for scanning devices and debugging templates.
-
-```bash
-npm install @rhizomatics/signalk-einklabel-plugin
-```
-
-## Configuration
-
-Use the standard configuration option in the SignalK menu for the plugin.
-
-![Plugin Configuration](docs/assets/screenshots/plugin_config.png)
-
-## Examples
-
-### Tide Clock
-
-![Tide Clock](docs/assets/screenshots/example_tidal_clock.png)
-
-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:
-
-- [signalk-tides](https://github.com/openwatersio/signalk-tides) - uses [neaps](https://github.com/openwatersio/neaps) library for international off-line coverage
-- [signalk-mareas-ihm](https://github.com/Aitonos/signalk-mareas-ihm) - interfaces with official Spanish IHM tidal predictions, or falls back to Open Meteo and _signalk-tides_
-
-The [tides](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tides/) templates can be customized to run with any tide provider, a specific one, or switch to other APIs or SignalK data paths.
-
-- In the template it uses a SVG description like `source=resources,resource=tides,provider=tides,path=extremes[0].time,format=local_time` to get the first tide time, ensures it's the preferred `signalk-tides` provider and makes it a simple local time rather than a UTC date-time.
-
-To show the lunar phase, the `environment.moon.phaseName` path is required, which can
-be easily achieved by installing and configuring the `derived-data` plugin.
-
-### Watch Schedule
-
-![Watch Schedule](docs/assets/screenshots/example_watch_schedule.png)
-
-Template available as 416x240-BWRY for 3.7" ESLs.
-
-#### Pre-requisites
-
-- Source of `watch.current` and `watch.next` values
-  - `signalk-watch-schedule` plugin
-
-## Setting up a Label
-
-Enable the plugin, and use the large **+** sign to add a label, which opens up these fields.
-
-![Label Config](docs/assets/screenshots/label_config.png)
-
-- _Friendly Name_ - Give the label any name (word or phrase) you like, for example 'Tide Clock'
-- _Device_ - Unless you have multiple labels, don't bother with pre-scanning or selecting a specific device, instead pick **"All discovered devices"** and it will paint any compatible labels it finds. If you want to pick a specific device, you'll need to wait for a device scan to complete.
-- _Template_ - Choose a built-in template, one you've added to the local templates directory, or - if a companion plugin like [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) is installed - one of its own contributed entries (shown with a suffix, e.g. "forecast (GenAI)")
-- _Location/description_ - Optional free-text notes on where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m in poor light" - available to any template as `source=label,path=description` (see [Label Details](#label-details))
-- _Repaint Trigger_- Do you want this to repaint every few hours (at a chosen minutes past hour), or when a SignalK path changes?
-  - If it's a SignalK path, enter it next, for example `environment.tide.state`
-  - If it's time based, enter how many hours between repaints, for example 00:00/08:00/16:00 for an 8h schedule, and if you want a specific number of minutes after the hour.
-
-The rest are grouped under _Advanced settings_, and can usually be ignored.
-
-- _If the render doesn't match the panel size_ - see [Reframing](#reframing)
-- _Compress upload_, _Mirror_ and _Wire format_ - see [Other Image Options](#other-image-options)
-- _Force Repaint_ - Next time the label is due to be painted, update even if the data or template hasn't changed (this flag will automatically be cleared after this.)
-- _BLE AES key_ - Only needed if the default key doesn't work and you have a better alternative, otherwise ignore
-- _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.
-
-### Scanning for Devices
-
-Since these are ultra-low power devices, they don't respond instantly to either identify themselves or accept a new image. By default, both scanning and painting have time-outs to wait for a response, which can be altered in the plugin configuration or CLI argument.
-
-One other quirk is that some devices respond with a different name at different times, for example the generic `WOESL` sometimes and model specific `WL17500C74` other times. However, the MAC address, e.g. `66:66:17:50:0D:2B` is constant, and this is what's tracked by the plugin.
-
-The plugin can optionally re-scan whenever it starts up (off by default), although this isn't essential once a label has been configured. Devices found by any scan are remembered across restarts - see the FAQ below.
-
-## Vendors
-
-### Zhsunyco
-
-Also known as 'Suny' and 'WOLink'.
-
-- [BLE ESLs](https://www.zhsunyco.com/digital-display-solution-for-small-retail-business/ble-esl-solution/)
-  - The range of labels available on retail sites like AliExpress may be larger than on their corporate site
-  - In mid 2026, a 4 colour (BWRY) 3.7" label retailed for about $35, with quantity discounts for bulk sets
-  - Cheapest units are 2 colour 1.54", and they go up to 7.5"
-
-Python code for a variety of their labels at https://github.com/roxburghm/zhsunyco-esl and https://github.com/NickWaterton/Wolink
-
-### Gicisky
-
-Known by other names, e.g. 'Picksmart', and with white label brands
-
-- BLE ESLs
-  - Official store is on [AliExpress](https://www.aliexpress.com/store/911771479/pages/all-items.html?productGroupId=40000001654819&spm=a2g0o.store_pc_home.pcShopHead_6000727597996.1_1)
-  - Cheapest labels under £10 GBP / $13 USD
-
-## Templating
-
-Templates are simply SVG files, to which expressions can be added to use SignalK data, with options to make it easier to read, like rounding or simplifying dates and times. The template can have sample data in the placeholder, so is easy to layout and visualize.
-
-### Reframing
-
-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.
-
-Each template is named `<width>x<height>-<colours>.svg`, where `<colours>` is one letter per supported colour: `B`(lack)/`W`(hite)/`R`(ed)/`Y`(ellow) - e.g. `BWRY` for a 4-colour panel, `BWR` for a 3-colour one.
-
-Selecting the directory (e.g. `tides`) instead of one file lets one `DeviceConfig` entry - especially a `device: "All discovered devices"` entry covering several different physical panels - automatically pick the best-fitting file for each device's actual size/colours, trying in order:
-
-1. An exact width/height/colour-set match.
-2. Failing that, width/height alone (any colour-set).
-3. Failing that too, the nearest width, tie-broken by whichever file's own height/width ratio is closest to the device's.
-
-### Template Source Specification
-
-In the `description` of the SVG text box, use a comma separated set of key value pairs to define the data source and formatting.
-
-#### SignalK Paths
-
-For example, `path=environment.forecast.description` uses the default data source (the `self` vessel context) and the named SignalK path. A bare path with no key/value pairs at all, e.g. just `environment.forecast.description`, is shorthand for the same thing. Overriding the default context can be done with `path=environment.forecast.description,context=vessels.urn:mrn:imo:mmsi:232345678` - the `context` value must match a real SignalK context exactly as it appears in the Data Browser.
-
-#### SignalK REST APIs
-
-The source can be overridden to use the SignalK server's Resources API instead. Change `source` to `resources` and specify which resource with `resource`. If there are multiple providers for the same resource, and they're not equally useful, then either set a default provider in SignalK, or use the `provider` tag to set the name.
-
-For example, `source=resources,resource=tides,provider=tides,path=station.name` picks the `tides` resource and pulls the `station.name` path out of the JSON response - this works for any resource type (`tides`, `waypoints`, `routes`, ...), and needs nothing configured: the plugin reaches the Resources API directly. Where a resource is specified, it will be fetched once for that render, and subsequent fields sourced from the same resource use that cached response. `provider` is optional, the default provider will be used if not specified.
-
-#### Plugin Derived Data
-
-`source=einklabel` reads data injected by the plugin itself, rather than from SignalK. Available paths:
-
-- `path=repainted` - the timestamp of the current repaint - for example `source=einklabel,path=repainted,format=local_datetime_short` to show when the label was last updated.
-- `path=local_zone` - a short zone name (e.g. `BST`) for the same timezone used for `local_time`/`day_mon`/`local_datetime_short` (see above) - a fallback for `environment.time.timezoneRegion,format=utc_offset` on installs that never publish that path, since it needs no SignalK metadata of its own. Falls back to a plain UTC offset like `GMT+1` where the host's locale has no real abbreviation for the zone.
-- `path=plugin_version` - expose the version of the eInk Label plugin itself.
-
-#### Label Details
-
-`source=label` reads facts about the label being painted, so one template can adapt to different labels. Available paths:
-
-- `path=description` - the label's _Location/description_ setting, e.g. `source=label,path=description`
-- `path=manufacturer` - the label's maker, e.g. `Zhsunyco`
-- `path=label` - the model's panel size, e.g. `3.7"`
-- `path=width` and `path=height` - the panel size in pixels
-- `path=colours` - the colours the panel can show, e.g. `black (#000000)`; add `format=csv` for a plain comma-separated list
-- `path=fonts` - the font families that are always available: `serif`, `sans-serif` and `monospace`
-- `path=position` - the vessel's position, rounded to about 1km
-
-These also work in the fallback warning shown when a template fails to render. Changing a label's description repaints it.
-
-#### Customizing Output
-
-A `format` can be specified to make the value easier to understand. The supported formats are:
-
-- `local_time` - reduce a time stamp to just the time (H:M:S), omitting the date, and applying daylight savings if appropriate
-- `day_mon` - reduce a time stamp to day and month, e.g. `27 Jun`, applying daylight savings if appropriate
-- `local_datetime_short` - format a time stamp as day, abbreviated month, 2-digit year and 24h time, e.g. `21 Jun 26 18:05`, applying daylight savings if appropriate
-- `utc_offset` - Show a timezone in `UTC+01:00` style format
-- `position` - Format a `{ latitude, longitude }` value as decimal degrees with hemisphere letters, e.g. `56.6250°N 6.0700°W`
-- `raw` - Don't apply automatic SignalK unit conversion and symbol display (see below)
-
-SignalK's unit preferences are used to automatically convert a `signalk`-sourced numeric value to its preferred display unit, and append a unit symbol like `kt` or `m`, unless `format=raw` is specified to switch that off. However, when using plugin or API data there may be no path metadata to convert from (for example `signalk-tides` publishes tide data to the Resources API, and `level` is a raw metre value with no SignalK path of its own) - in these cases an explicit `category` can be given instead, and the unit preferences will be applied the same way, for example `category=depth` for the tides level figure.
-
-Note that for dates and times, the server timezone must be set correctly, for example `Europe/London` rather than the default `Etc/UTC`. This can be done on Linux using `timedatectl` or `raspi-config` if using a Raspberry Pi with Raspian.
-
-##### Common categories
-
-- `depth` - Use the SignalK preferred depth unit, make the conversion if needed, and tack on the unit name as a suffix
-- `speed` - Use the SignalK preferred speed unit, make the conversion if needed, and tack on the unit name as a suffix
-- `temperature` - Use the SignalK preferred temperature unit, make the conversion if needed, and tack on the unit name as a suffix
-
-Additionally, `round=n` can be used to round to limited decimal places.
-
-`default=<value>` substitutes `<value>` whenever the resolved value is missing (e.g. an unpublished path), instead of falling through to an empty string - useful anywhere a blank would be misread as a real answer. `default=` with nothing after the `=` still counts as set, deliberately defaulting to an empty string rather than leaving the fallback behaviour unchanged.
-
-These can all be combined as in `source=resources,resource=tides,provider=tides,path=extremes[2].level,category=depth,round=2`
-
-### Non-Textual Fields (Images)
-
-The same `<desc>` mechanism works on an `<image>` element instead of a `<text>` element, for a value that's better shown as a picture than as text - a moon phase icon, a wind direction arrow, a weather condition glyph, and so on. Rather than substituting text, the resolved value picks one of a directory of `.svg` files to embed, by an extra required `assets=` key naming that directory - an `.assets/<name>` sub-directory looked up in your configured `templates` directory first, and the bundled `templates` directory otherwise. For example, the tide clock's moon phase icon uses:
-
-```
-path=environment.moon.phaseName,assets=lunar_phases
-```
-
-which resolves against `templates/.assets/lunar_phases/` (bundled, or your own configured `templates` directory's `.assets/lunar_phases/` if you have one). The resolved value (e.g. `"Waning Gibbous"`, as published by the [derived-data](https://www.npmjs.com/package/signalk-derived-data) plugin) is normalized to match a filename - lower-cased, punctuation and spaces collapsed to underscores - so `"Waning Gibbous"` picks `waning_gibbous.svg` out of that directory. If the underlying path has no value at all (e.g. the `derived-data` plugin isn't installed), or the value doesn't normalize to any file in the directory, the `<image>` element is omitted from that render - no broken image, no placeholder, nothing shown - and a line is logged to the console so a missing/unmatched value isn't silently invisible.
-
-If you don't like the bundled moon phase icons, save your own `<value>.svg` files in the `.assets/lunar_phases` sub-directory of your configured `templates` directory - the whole directory is used in place of the bundled one, so add all 8 phases you want to keep, not just the ones you're changing. These moon phases can be re-used in any other label.
-
-This is a general mechanism, not specific to moon phases - any `source`/`context`/`path`/`format` combination valid for a `<text>` binding works here too (a `source=resources` value, an explicit `category=`, etc.), the only difference is the required `assets=` directory and the "no match -> no image" behaviour instead of substituted text. To add your own, put a directory of `<value>.svg` files under an `.assets/<name>` sub-directory of your `templates` directory, add an `<image>` element in your SVG editor at the size/position you want, and give it a `<desc>` the same way you would a text field - overriding just the template, just its assets, or both together, all work independently.
-
-### Fonts
-
-Three font types are loaded by default, use the generic font family, or exact font name, in the SVG editor and choose size and weight (bold, semi-bold etc). Some labels will make a decent attempt to gray scale. Use the simple pure red, yellow, white, black to match the label's limited colour choice (some labels only offer black and white, or black/white/red). If a font can't be matched it will default to (sans-serif) Roboto.
-
-- `serif` - `Roboto Serif`
-- `sans-serif` - `Roboto`
-- `monospace` - `Roboto Mono`
-
-## GenAI Rendering
-
-As an alternative to hand-designed SVG templates, a device's content can be generated by an LLM instead - this is provided entirely by a separate companion plugin, [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin), not by this core plugin. The base plugin (BLE painting, SVG templates) has nothing to do with any LLM SDK or API key, so installing it never pulls in GenAI dependencies unless you also explicitly install and enable the companion plugin - the split is deliberate, for anyone on a small/constrained install or who'd simply rather not have any GenAI code in their install at all.
-
-Once the companion plugin is installed and enabled, its own config screen handles provider/model/API-key selection (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot AI, Ollama, or any other OpenAI-compatible endpoint), and its prompts show up as ordinary entries in this plugin's "Template" dropdown, suffixed (e.g. "forecast (GenAI)") - pick one exactly like you'd pick a `.svg` file. Under the hood it's a `TemplateProvider` (see [Extending](#extending) below) - the same extension mechanism a new vendor's hardware driver uses - so from this plugin's point of view it's just another way `templateName` gets resolved to an image.
-
-If the LLM call fails (network/API error, exhausted retries) or its response isn't renderable, this core plugin pushes its own bundled warning template instead of leaving the previous, possibly now-wrong, content on screen - so a stale weather prompt never quietly shows yesterday's forecast through today's storm. This is a generic safety net, not GenAI-specific: the exact same fallback covers a broken hand-authored template failing to render at all. The next scheduled repaint retries automatically. Since each repaint may call a (usually paid) LLM API, a GenAI-backed device should use Repaint Trigger `interval`, not `subscription`.
-
-See the companion plugin's own README for installing it, writing prompts, and its `esl-cli prompt`/`generate` commands for testing prompts without a device.
-
-## Architecture
-
-The primary things managed and provided by the plugin are:
-
-- ESL Vendor
-  - Sub-package per vendor
-- ESL Device
-  - Metadata in the vendor package, using a `pid` or sometimes `pid` combined with `hwid` in the BLE results to pinpoint a model
-- SVG Template
-- SignalK API base URL
-  - Used for automatic unit conversion on `signalk`-sourced numeric values and for resolving an explicit `category=` binding - neither has an in-process equivalent, both go via this server's own REST API
-  - Optional: left blank, the plugin probes the probable values in likelihood order at startup - `http://localhost:3000`, `http://localhost`, `https://localhost`. Set it explicitly to skip probing
-  - Either way, errors clearly if nothing responds (wrong port) or the probe is rejected (anonymous read access not enabled) - these endpoints must allow anonymous read access, since the plugin has no login flow
-
-## Command Line Interface
-
-To get fast feedback on templates and shelf devices without updating and configuring SignalK, a CLI call `esl-cli` is provided when the module is manually installed that has these commands. Use `--help` to get all the options.
-
-- `vendors` - list supported vendors
-- `scan` - report supported devices found from a BLE scan
-
-See also the commands useful for debugging under [Developing Templates]
-
-- `render` - transform an SVG template and data into a PNG
-- `paint` - render an SVG template and data to a selected ESL
-
-The width, height, vertical offset and colour palette for the device are taken from the internal register of devices, however can be overridden on the command line with `-w/--width`, `--height`, `--voffset` and `--colours`. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
-
-Left unset, both `render` and `paint` default `-w/--width`/`--height` to the template's own declared `width`/`height` (or `viewBox`) - neither command connects to a device just to size the render, since that would mean an extra BLE connect ahead of `paint`'s own, and doing two back-to-back is exactly the kind of churn that trips real BLE hardware.
-
-`paint` also takes `--reframe <mode>`, applied once it has connected and identified the device, for when the rendered image doesn't come out the same size as its actual panel (see [Reframing](#reframing) above):
-
-- `crop` (default) - keeps pixels 1:1, placed from the top-left; a bigger render is truncated to fit, a smaller one leaves the extra panel space blank
-- `scale` - stretches the rendered image onto the panel's exact dimensions (independently per axis, not preserving aspect ratio)
-- `fixed` - no adjustment; rejects a size mismatch with an error instead
-
-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` )
-
-### Scans from CLI
-
-The command line tools, run from inside the `.signalk` directory, can be used to help troubleshoot
-
-- Scan for longer, in this example 90 seconds
-  - `npx esl-cli scan -d 90`
-- Scan for all BLE devices, whatever they are
-  - `npx esl-cli scan -a`
-
-## Extending
-
-### Hardware
-
-Additional vendors and devices can be added by a separate npm package that implements the `VendorDriver` interface and registers itself - there's no scanning of installed packages, registration is always an explicit call by the extension's own code.
-
-- `import esl from '@rhizomatics/signalk-einklabel-plugin'; esl.registerVendorDriver(myDriver)`
-- In the SignalK runtime, call this from the extension's own plugin `start()`. In the CLI, load the extension with `esl-cli --require <module> <command>`.
-- Declare this package as a regular npm `dependency` in the extension package - **not** a `peerDependency`, per SignalK's own guidance that npm's peer-dependency resolution interacts poorly with the server's plugin install layout - and declare the SignalK-level relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the extension's own `package.json` instead, so the App Store can install/report it.
-
-### Template Providers
-
-An alternative way to produce a device's content, alongside hand-authored SVG templates, can be added the same way - `esl.registerTemplateProvider({ suffix, listTemplates, render })`, from a separate package's own plugin `start()` (or `esl-cli --require <module>`). This is what [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) is: `listTemplates()` returns the entries it currently offers (already including its own `suffix`, e.g. `"forecast (GenAI)"`) for the "Template" dropdown, and `render(request)` - given the same signalk/resources/label context any SVG template's bindings get - returns a `Bitmap`, exactly as `SvgRenderer.render()` would. Rejecting from `render()` routes the repaint through this plugin's own generic fallback-warning template, the same as a broken hand-authored template failing to render.
-
-`esl.SvgRenderer`, `esl.buildLabel`, `esl.findBindingsInText`, and `esl.substituteBindingsInText` are also exported for a `TemplateProvider` extension to reuse - e.g. to resolve its own `{...}`-style placeholders against the request's context, or to rasterize whatever SVG it produces into the `Bitmap` its `render()` must return.
-
-### Developing Templates
-
-See the [Templating] section for more details.
-
-Templates can be added to the configurable directory. [Inkscape](https://inkscape.org) free, open source, and recommended for editing templates, or your own favourite editor, or by hand in a text editor for hard core (or just tidying up the template side).
-
-![Example Field Definition](docs/assets/screenshots/inkscape_desc.png)
-
-The object ID and label aren't used by the plugin, only the description is used to define fields. You can also add in ordinary text fields without field definitions, as labels, logos, help text etc.
-
-Placeholder text isn't necessary, and is ignored by the plugin, but makes it much easier to visualize the result.
-
-Inkscape adds its own metadata to images, which can be stripped off by exporting a simple SVG, although can be left in place with no harm; main reason to simplify the SVG is manual changes in a text editor.
-
-Due to a limitation in the `resvg-wasm` library used to turn SVGs into images, the `font-family` is limited to `serif`,`sans-serif`,`monospace` or the exact name of one of the installed fonts - `Roboto` (sans serif), `Roboto Serif` or `Roboto Mono`.
-
-Inkscape has its own fonts, which won't match what's available in the SignalK plugin, so for more precise design, install [Roboto from Google](https://fonts.google.com/specimen/Roboto) via the web page, `brew` on MacOS or similar.
-
-### Debugging Templates
-
-The `esl-cli` can be used to debug and validate templates quickly:
-
-- `render` - Render templates with SignalK data and write to a local PNG file
-- `paint` - Render templates with SignalK data and send to selected ESL device
-- `fields` - List the fields in the template, with the source specification and the rendered data value
-- `field` - Accept a source specification (outside of any template context) and return the rendered value if available
-
-Use `--help` to get the full set of arguments for any of the commands.
-
-### Examples
-
-#### Paint Image Directly
-
-The label address previously discovered via `esl-cli scan`
-
-```bash
-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), 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).
-
-```bash
-npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -u http://localhost
-```
-
-and this version will work even without a running SignalK server, using some pre-packaged example data:
-
-```bash
-npx esl-cli render -t templates/tides/250x128-BWRY.svg -o example.png -e examples
-```
-
-#### List all Fields and Rendered Values
-
-```bash
-npx esl-cli fields -t templates/tide.svg -u http://localhost
-```
-
-```
-id                   spec                                                                                    value
-station.name         source=resources,resource=tides,provider=tides,path=station.name                        Tobermory
-source.name.         source=resources,resource=tides,provider=tides,path=station.source.name                 TICON-4
-last_repaint         source=einklabel,path=repainted,format=local_datetime_short                             30 Jun 26 00:08
-extremes.0           source=resources,resource=tides,provider=tides,path=extremes[0].label                   Low
-extremes.1           source=resources,resource=tides,provider=tides,path=extremes[1].label                   High
-extremes.2           source=resources,resource=tides,provider=tides,path=extremes[2].label                   Low
-timezoneRegion       source=einklabel,path=local_zone                                                        BST
-lat                  source=resources,resource=tides,provider=tides,path=station.datums.LAT,category=depth   0.2m
-hat                  source=resources,resource=tides,provider=tides,path=station.datums.HAT,category=depth   5.2m
-extremes.2.level     source=resources,resource=tides,provider=tides,path=extremes[2].level,category=depth    1.1m
-extremes.2.time      source=resources,resource=tides,provider=tides,path=extremes[2].time,format=local_time  13:15
-extremes.1.level     source=resources,resource=tides,provider=tides,path=extremes[1].level,category=depth    3.8m
-extremes.1.time      source=resources,resource=tides,provider=tides,path=extremes[1].time,format=local_time  07:05
-extremes.0.time      source=resources,resource=tides,provider=tides,path=extremes[0].time,format=local_time  01:21
-extremes.0.time-8    source=resources,resource=tides,provider=tides,path=extremes[0].time,format=day_mon     30 Jun
-extremes.0.time-8-5  source=resources,resource=tides,provider=tides,path=extremes[1].time,format=day_mon     30 Jun
-extremes.0.time-8-9  source=resources,resource=tides,provider=tides,path=extremes[2].time,format=day_mon     30 Jun
-extremes.0.level     source=resources,resource=tides,provider=tides,path=extremes[0].level,category=depth    1.3m
-```
-
-### Offline Working
-
-`render` and `paint` need a `--url` argument to point to the SignalK server to retrieve data. If you don't have access to one, you can use `--example-data` or `-e` to point to a directory of example data, which is bundled with the plugin or available in GitHub at [examples](https://github.com/rhizomatics/signalk-einklabel-plugin/tree/main/examples). This also allows you to write templates for resource APIs that aren't available yet.
-
-- `vessels.json` - The standard SignalK vessel paths
-- `resources/xxxx.json` - The output of the `xxxx` resources API call
-- `categories.json` - SignalK unit categories needed for `category=depth` type formatting
-
-For example, `npx esl-cli fields -t templates/tide.svg -e examples` will show all the field data that will be populated from the example API, vessel and category data in the `examples` local directory.
-
-## Frequently Asked Questions
-
-### I can't see my device as a choice on the drop-down list after scan
-
-SignalK plugins lack the ability to self-update after something like a scan, so first time round you may have to close the config and reload it to see this. Subsequently the plugin will remember all scanned devices, and only drop previously seen ones if it goes 24 hours without a positive scan or with failed paint attempts.
-
-Easiest way to solve this is to choose 'All Discovered Devices' in the device configuration, and it will paint any compatible devices it finds on future scans.
-
-### Sometimes values are missing on the display
-
-If the plugin repaints a display at server startup, then the plugin that provides the data may not have started ( or in the case of `derived-data` the plugin that the plugin depends on! ) and unlike Home Assistant, there's no good way of sequencing the start of plugins.
-
-Use the _settle_ time, to impose a minimum wait between the eInk Label plugin being initialized, and it attempting to paint any displays, and increase this value if it's still missing data.
-
-### Times are showing incorrectly {#faq-timezone}
-
-If times are in the wrong timezone, or don't have daylight savings applied correctly,
-then check that the server itself (at the Linux level, not SignalK, which doesn't know) is configured for your timezone, assuming of course that you're a coastal sailor. Use `raspi-config` on a Raspberry Pi, or `timedatectl` on a Linux server.
-
-If you're a global cruiser, then use something like [signalk-set-gps-timezone](https://github.com/hoeken/signalk-set-gps-timezone) to set the value in the operating system.
-
-### The ESL signal is too weak from my SignalK server
-
-Try a BLE proxy device, ESP32 is popular for this.
-
-### Can't edit the text contents of SVG template in VSCode
-
-If you have an SVG viewer extension, this will show the image rather than allowing editing of text. To solve, right click on the file in VSCode _Explorer_ view and choose to edit with _Text Editor_.
-
-### Description is set in InkScape but doesn't render
-
-Check if the text boxes are normal text or flowed text, and correct to normal text.
-
-### My label just shows "CONTENT UNAVAILABLE"
-
-That's the bundled fallback warning, not necessarily an error in this plugin - it means the most recent repaint failed, whatever produced the content (a broken hand-authored template, or a `TemplateProvider` extension like [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) - e.g. its LLM call failing on no network/API access, an invalid API key, or a response that wasn't a renderable SVG, after using up its configured retries). Check the SignalK server logs (debug logging on for this plugin) for the specific error, and if it's a GenAI device, check that plugin's own provider/API key/model settings. This plugin deliberately never leaves old content on screen when a repaint fails - it retries automatically at the next scheduled interval.
-
-### 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:
-
-```bash
-sudo systemctl edit signalk.service
-```
-
-This opens an override file — add:
-
-```ini
-[Unit]
-After=bluetooth.target
-Wants=bluetooth.target
-```
-
-Save and exit, then:
-
-```bash
-sudo systemctl daemon-reload
-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"
-```
+- [Getting Started](https://signalk-einklabel.rhizomatics.org.uk/getting-started/) - pre-requisites, installation, setting up a label, and which labels to buy
+- [Templates](https://signalk-einklabel.rhizomatics.org.uk/templates/) - how templates work, binding them to SignalK data, and designing your own
+- [Examples](https://signalk-einklabel.rhizomatics.org.uk/examples/) - the bundled templates, with the sizes and data each one uses
+- [Bluetooth](https://signalk-einklabel.rhizomatics.org.uk/bluetooth/) - choosing an adapter and keeping Bluetooth reliable
+- [FAQ](https://signalk-einklabel.rhizomatics.org.uk/faq/) - answers to common problems
+- [Command Line Interface](https://signalk-einklabel.rhizomatics.org.uk/cli/) - the `esl-cli` tool for testing templates and labels without SignalK
+- [Extending](https://signalk-einklabel.rhizomatics.org.uk/extending/) - adding label hardware or new ways of producing content
 
 ## Other ESL and General eInk Resources
 

package/dist/cli/index.js

@@ -291,6 +291,7 @@ exports.program
             mirror: parseMirrorMode(opts.mirror),
             compress: opts.compress,
             compressionFormat: parseCompressionFormat(opts.compressionFormat),
+            log: log_1.logDebug,
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);

package/dist/config.d.ts

@@ -187,6 +187,22 @@ export declare function parseDevice(device: string): {
     hwVersion?: string;
     address: string;
 } | undefined;
+export declare function listSvgFiles(dir: string): string[];
+export interface TemplateVariant {
+    fileName: string;
+    width: number;
+    height: number;
+    colours: Colour[];
+}
+export declare function listTemplateVariants(dir: string): TemplateVariant[];
+/**
+ * A directory only counts as a template-family option if it actually has at least one parseable
+ * variant file in it - otherwise it's something else entirely, e.g. `.assets`. Dot-prefixed
+ * directories (e.g. `.assets`, `.blank`) are always excluded, even if they happen to contain
+ * parseable variant files, since they're reserved for non-template-option use (asset bundles,
+ * work-in-progress templates not ready to appear in the dropdown, etc).
+ */
+export declare function listTemplateFamilies(dir: string): string[];
 /**
  * Resolves a template name to an actual file path - a local template overrides the bundled one of the
  * same name. `templateName` can also name a template-family *directory* (see `pickBestVariant`), in