@rhizomatics/signalk-einklabel-plugin 1.3.0-beta9 → 1.3.1

package/docs/cli.md

@@ -0,0 +1,131 @@
+# 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 (see [Using Outside of SignalK](getting-started.md#using-outside-of-signalk)) that has these commands. Use `--help` to get all the options.
+
+- `vendors` - list supported vendors
+- `scan` - report supported devices found from a BLE scan
+- `render` - transform an SVG template and data into a PNG
+- `paint` - render an SVG template and data to a selected ESL
+- `fields` and `field` - see [Debugging Templates](#debugging-templates)
+
+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](templates.md#reframing)):
+
+- `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](templates.md#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 - see [Extending](extending.md#cli-commands).
+
+( 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`
+
+## 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.
+
+## CLI 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.

package/docs/design/roadmap.md

@@ -0,0 +1,9 @@
+# Design Plans
+
+## Label Support
+
+- More vendors, and more labels for existing vendors
+- Ability for people to plug-in vendor support for themselves or as published plugins
+- A model override in the plugin config, so a discovered device whose PID isn't in its driver's table yet can be repainted (the CLI's `paint --colours` already does this)
+- Neaps or springs status (e.g. "Springs +1", "Neaps -2") on the tide template, pending upstream signalk-tides support
+- Alternatives to SVG templates, perhaps [imagespec](https://pypi.org/project/imagespec/) or [signalk-hmi-designer](https://github.com/dirkwa/signalk-hmi-designer)

package/docs/design/spec.md

@@ -0,0 +1,59 @@
+# Design Specification
+
+A SignalK plugin, in TypeScript, that renders selected SignalK data to BLE eInk Electronic Shelf Labels (ESLs). This page describes the plugin as it is built. Plans and ideas not yet built are in the [roadmap](roadmap.md).
+
+# Features
+
+- Native TypeScript, Node 20 compatible (runs on armv7, e.g. a Cerbo GX)
+- Bundled templates for a tide clock and a watch schedule, rendered from any SignalK data, Resources API resource or label fact a template binds to
+- Pluggable vendor support
+  - Built-in drivers for Zhsunyco and Gicisky BLE labels (`src/devices/zhsunyco/`, `src/devices/gicisky/`), registered by `plugin.ts` at startup
+  - Each driver has a metadata table of the models it supports, keyed by PID, with `hwVersion` used where a vendor reuses a PID across panel sizes. Each entry gives the label, width, height, vertical offset and colours. `esl-cli vendors` lists them
+  - Additional vendors are added by a separate npm package implementing `VendorDriver` and calling the exported `registerVendorDriver` explicitly - no scanning of installed packages. In the SignalK runtime the extension calls it from its own plugin `start()`; the CLI loads it via `esl-cli --require <module>`. Extension packages declare this package as a regular `dependency`, not a `peerDependency` (SignalK's guidance is 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"] }` - see [Extending](../extending.md)
+  - The config schema's device and template options are read live from the registries when the schema is built, so a newly-registered extension shows up the next time the config panel is opened
+- Bluetooth access, either direct or shared
+  - Direct BlueZ access over D-Bus via `node-ble` (the default). The plugin waits, with backoff, for a local adapter before scanning or painting, to cover the boot-time race where the plugin starts before BlueZ is ready
+  - The SignalK BLE Manager API (`app.bleApi`, server >= 2.32.0), opted into with `useBleApi`, so the plugin shares the adapter with other BLE plugins. Only offered in the config schema when the running server has it. Paints through BLE Manager are serialised so only one label holds a GATT connection at a time
+- Device discovery
+  - One shared discovery path across all registered drivers (`discoveryCoordinator.ts`): each advertisement is read once and offered to each driver's `matchesAdvertisement`; only a matching driver's `identifyDevice` runs, which may open a GATT connection when the advertisement alone doesn't identify the model
+  - A scan already in progress is joined rather than a second one started, since neither backend can run two discovery sessions at once
+  - With direct BlueZ access, scanning happens in bounded windows: an optional startup scan (`scanOnStart`, off by default, `scanDurationSeconds` long), an on-demand scan when an "All discovered devices" entry has nothing discovered yet, or `esl-cli scan`. With BLE Manager, the plugin listens to its advertisement stream for as long as the plugin runs, and only identifies new addresses
+  - Discovered devices are persisted in the plugin data directory, keyed by BLE address, and kept for 24 hours after last being seen; a successful paint counts as being seen. The startup scan reports what it found in the plugin status line
+  - The device picker lists any device a driver identified as its vendor, even if the PID isn't in that driver's metadata table yet (labelled "vendor unrecognised PID 0x.... (address)"), so it can be reported. Such a device can't be repainted from the plugin, since there's no width/height to render with; `esl-cli paint` can paint one by supplying the model facts on the command line
+- Device configuration
+  - Each device entry has a friendly name, a combined "Device" choice, an optional location/description, a template and a repaint trigger, with less common settings grouped under "Advanced settings"
+  - The "Device" value is `"<vendor>:<pid>[:<hwVersion>]@<address>"`, picked from recently discovered devices, so width/height/colours are known from config alone and never need a live BLE read or a rescan after a restart. The special value `ALL` ("All discovered devices") paints the same template and trigger to every currently-known device instead, resolved at repaint time
+  - Advanced settings: reframe (`crop` by default, `scale`, or `fixed` to fail on a size mismatch), compress upload (on by default), mirror (`none`, `horizontal`, `vertical`, `both`), Gicisky wire format (`auto` or experimental `chunked`), Zhsunyco write-without-response, force repaint, Zhsunyco AES key (falls back to a default key), and per-device overrides of the plugin-wide paint connect timeout and retry count
+  - Config saved before advanced settings were grouped, or nested by an older save bug, is rewritten into the current shape at plugin start (`healStoredConfig`)
+- Templates
+  - SVG files, rendered to bitmaps with resvg-wasm (`src/render/svgRenderer.ts`). A user templates directory (`templatesDir`: empty for `~/.signalk/einklabel/templates`, relative to `~/.signalk`, or absolute) is scanned alongside the bundled `templates/` directory; a user template with the same name as a bundled one takes priority. There is no upload UI
+  - A template is either a single `.svg` file or a _template family_: a directory of variants named `<width>x<height>-<colours>.svg` (e.g. `tides/416x240-BWRY.svg`). The best variant for each device is picked at repaint time: exact size and colours, then exact size, then the nearest width with the closest aspect ratio. Dot-prefixed directories (`.assets`, `.blank`, `.error`) are never offered as templates
+  - Each template can be assigned to one or more devices. There is no separate data config; a template's own bindings declare what data it needs, re-read from the template on every repaint
+  - Text uses the bundled serif, sans-serif and monospace fonts (resvg-wasm can't see system fonts); the generic CSS family names are rewritten to the bundled fonts' exact names
+- Bindings
+  - A dynamic `<text>` element carries a flat `key=value,key=value` binding in a `<desc>` child, not a templating engine - e.g. `source=resources,resource=tides,path=extremes[0].time,format=local_time`. `source`/`context` default to `signalk`/`self`, a bare path with no `=` is shorthand for `path=...`, and array indices use bracket notation. The element's own text is a placeholder for laying out the template in an editor. See `src/render/binding.ts` for the grammar
+  - Keys: `source`, `context`, `resource`, `provider`, `path`, `format`, `category`, `round`, `assets`, `default`. An unknown key is an error; `default=` replaces a missing value
+  - `source=signalk` (default): `context=self` reads via `getSelfPath`; any other `context` is read via `getPath` against that literal SignalK context, exactly as shown in the Data Browser (e.g. `vessels.urn:mrn:imo:mmsi:232345678`)
+  - `source=resources`: `resource=<name>` reads any Resources API resource type (`tides`, `waypoints`, ...) via `app.resourcesApi.listResources` in-process. `provider=<plugin id>` pins it to one resource provider; a pinned binding goes over the REST API instead, since the in-process call ignores the provider id (signalk-server 2.30.0)
+  - `source=label`: facts about the physical label - `manufacturer`, `label`, `width`, `height`, `colours`, `fonts`, `description`, and `position` (rounded to about 1km so GPS jitter doesn't force repaints)
+  - `source=einklabel`: plugin-injected values - `repainted` (repaint time), `local_zone` (timezone abbreviation) and `plugin_version`
+  - `format=` names a formatter from `src/render/formatters.ts`: `local_time`, `day_mon`, `local_datetime_short`, `utc_offset`, `position`, `csv`. Times use the vessel's `environment.time.timezoneRegion` when published, otherwise the host's timezone - never a tide station's own `timezone` field
+  - A `signalk`-sourced numeric value converts to its path's preferred display unit by default, via `GET {signalkApiUrl}/signalk/v1/api/vessels/<context>/meta` (there's no in-process equivalent); `format=raw` opts out. A value with no path of its own (e.g. resource-sourced) can take an explicit `category=<name>` (e.g. `category=depth`), resolved from `{signalkApiUrl}/signalk/v1/unitpreferences/...` client-side (`src/unitCategories.ts`). `round=` sets decimal places
+  - An `<image>` element with a `<desc>` binding and an `assets=<name>` key picks one `.svg` from an asset directory (`.assets/<name>/`, user templates directory first, then bundled) by the resolved value, e.g. the bundled `lunar_phases` icons for `environment.moon.phaseName`. The element is dropped when the value is missing or has no matching file
+- SignalK API base URL
+  - `signalkApiUrl` is optional. Left unset, `resolveSignalkApiUrl` (`src/resolveApiUrl.ts`) probes `http://localhost:3000`, `http://localhost` and `https://localhost`, in that order, at the first repaint and caches whichever responds. Always the loopback address, since the plugin runs on the same host as the server. Setting it explicitly skips probing but is still verified
+  - It errors clearly if nothing responds (wrong port) or every probe is rejected (anonymous read access not enabled) - these endpoints need anonymous read access, since the plugin has no login flow. A failed resolution is retried on the next repaint rather than cached
+  - Path metadata is best-effort (no server just means raw values); a `category=` or `provider=` binding without a reachable server fails the render
+- Repainting
+  - Each device picks one repaint trigger: a change on a SignalK path (`subscription`, debounced by 2 seconds, ignoring transient null/missing values), or a fixed interval (every N hours at a configurable minute past the hour, checked by one shared one-minute timer rather than one per device)
+  - Every trigger waits for a settle window after plugin start (`settleSeconds`, default 120), so a template isn't rendered before other plugins (e.g. derived-data) have published its data. After that window each device is checked once; an interval device already painted for its current slot skips this catch-up
+  - Before repainting, the template's mtime and the assembled data (bindings plus label facts, before plugin-injected values like the repaint time are added) are hashed and compared against the last successful paint, persisted in the plugin data directory per device entry and BLE address (`friendlyName:address`). If both are unchanged the repaint is skipped, to save the label's battery and avoid a full-panel flash. A template provider's output always repaints, since the plugin can't know whether it would differ
+  - "Force repaint" bypasses the unchanged-data skip for one repaint, then clears itself once every target device has painted successfully
+  - Only one repaint per device entry runs at a time; a trigger arriving mid-repaint queues one follow-up, run only if the current repaint succeeded
+  - A paint is retried up to `paintRetries` times (default 3, 5 seconds apart), each attempt bounded by `paintConnectTimeoutSeconds` (default 30) plus a backstop deadline
+  - Stopping the plugin (a config save, disable, or server shutdown) stops every trigger, drops queued follow-ups and retries, and skips a paint that hasn't connected yet. `stop()` returns a Promise that resolves once a paint already under way has finished, waiting at most 30 seconds, and the next `start()` also waits for it, so two BLE sessions don't overlap
+  - If rendering fails (a broken template, a missing file, or a template provider's `render()` rejecting), the bundled `.error` warning template is painted instead, so stale content is never left on screen unmarked. No success hash is saved, so the next trigger retries
+- Template providers
+  - An extension package can offer content generated another way, alongside SVG templates, via `registerTemplateProvider` - e.g. `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt. Its entries appear in the same "Template" dropdown, marked by the provider's `suffix`. See [Extending](../extending.md) and `src/render/templateProviders.ts`
+- `esl-cli`, a local CLI for scanning, painting and testing templates outside the SignalK plugin
+  - `vendors`, `scan`, `paint` (with the same image options as the plugin, plus `--colours`/`--width`/`--height`/`--voffset` model facts for hardware not yet in a driver's table), `render` (template to PNG), `fields` (every binding in a template with its resolved value) and `field` (one binding spec). Bindings resolve against a live SignalK server over HTTP, or against local example JSON (`-e examples`). Extensions can add subcommands via `--require`. See [Command Line Interface](../cli.md)

package/docs/examples/README.md

@@ -0,0 +1,25 @@
+# Examples
+
+The plugin comes with ready-made templates for these examples. Pick one as a label's _Template_ in the plugin config, or copy it into your own templates directory as a starting point - see [Templates](../templates.md).
+
+- [Tide Clock](tide-clock.md) - the next few high and low tides, with the moon phase
+- [Watch Schedule](watch-schedule.md) - who's on watch now and next
+
+## Bundled Templates
+
+Every bundled template, with its sizes and the data it needs. Each example's page lists the exact labels each size fits and every field it reads.
+
+<!-- BEGIN GENERATED: templates-summary -->
+<!-- Generated from the bundled templates by `npm run docs:templates` - do not edit by hand. -->
+
+| Template                     | Sizes                     | Data needed                                                                                                                                                                     |
+| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`tide.svg`](tide-clock.md)  | 416×240                   | `tides` resource (provider `tides`), Signal K `environment.moon.phaseName`                                                                                                      |
+| [`tides`](tide-clock.md)     | 416×240, 296×128, 250×128 | `tides` resource (provider `tides`), Signal K `environment.moon.phaseName`                                                                                                      |
+| [`watch`](watch-schedule.md) | 416×240                   | Signal K `watch.current.endTime`, `watch.current.startTime`, `watch.current.teamName`, `watch.next.endTime`, `watch.next.startTime`, `watch.next.teamName`, `watch.system.name` |
+
+<!-- END GENERATED -->
+
+## Trying Examples Without a Boat
+
+Each template can be rendered to a PNG with the CLI using the bundled example data, with no SignalK server or label needed - see [Test Template Without Updating Label](../cli.md#test-template-without-updating-label).

package/docs/examples/tide-clock.md

@@ -0,0 +1,93 @@
+# Tide Clock
+
+![Tide Clock](../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](../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_
+
+For versions with the moon phases:
+
+- [signalk-derived-data](https://github.com/SignalK/signalk-derived-data) - unlike other plugins, this publishes lunar and solar facts as SignalK paths
+
+The moon phase is optional - without it, the moon icon is simply left blank and the rest of the tide clock still shows.
+
+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.
+
+> [!TIP]
+> If testing this without a boat, you'll need another plugin to provide `navigation.position` and `navigation.datetime` to make the moon and tide calcuations work. [signalk-datetime](https://github.com/tmcolby/signalk-datetime) can be configured for the datetime, and [signalk-sailboat-simulator](https://github.com/macjl/signalk-sailboat-simulator) for the postion; other ways may work too.
+
+## Template Reference
+
+The `tides` template family picks the best size for each label automatically - see [Template Families](../templates.md#template-families-multiple-panel-sizescolours).
+
+<!-- BEGIN GENERATED: template-reference tides -->
+<!-- Generated from the bundled templates by `npm run docs:templates` - do not edit by hand. -->
+
+**Template:** `tides`
+
+| File                                                                                                                           | Size (px) | Aspect ratio | Colours                   | Fits these labels exactly                                                |
+| ------------------------------------------------------------------------------------------------------------------------------ | --------- | ------------ | ------------------------- | ------------------------------------------------------------------------ |
+| [`tides/416x240-BWRY.svg`](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tides/416x240-BWRY.svg) | 416 × 240 | 1.73 : 1     | black, white, red, yellow | Zhsunyco 3.7" BWRY                                                       |
+| [`tides/296x128-BWRY.svg`](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tides/296x128-BWRY.svg) | 296 × 128 | 2.31 : 1     | black, white, red, yellow | Zhsunyco 2.9" BWRY, Gicisky 2.9" BW, Gicisky 2.9" BWR, Gicisky 2.9" BWRY |
+| [`tides/250x128-BWRY.svg`](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tides/250x128-BWRY.svg) | 250 × 128 | 1.95 : 1     | black, white, red, yellow | Zhsunyco 2.13" BWRY, Gicisky 2.1" BWR                                    |
+
+**Data used**
+
+| Source                              | Path                         | Options                               | Used in                    |
+| ----------------------------------- | ---------------------------- | ------------------------------------- | -------------------------- |
+| `tides` resource (provider `tides`) | `extremes[n].label`          | -                                     | all                        |
+| `tides` resource (provider `tides`) | `extremes[n].level`          | category `depth`                      | all                        |
+| `tides` resource (provider `tides`) | `extremes[n].time`           | format `local_time`, format `day_mon` | all                        |
+| `tides` resource (provider `tides`) | `station.datums.HAT`         | category `depth`, round 1             | 416x240-BWRY               |
+| `tides` resource (provider `tides`) | `station.datums.LAT`         | category `depth`, round 1             | 416x240-BWRY               |
+| `tides` resource (provider `tides`) | `station.name`               | -                                     | all                        |
+| `tides` resource (provider `tides`) | `station.source.name`        | -                                     | 416x240-BWRY, 296x128-BWRY |
+| Plugin                              | `local_zone`                 | -                                     | 416x240-BWRY, 296x128-BWRY |
+| Plugin                              | `plugin_version`             | -                                     | 416x240-BWRY               |
+| Plugin                              | `repainted`                  | format `local_datetime_short`         | all                        |
+| Signal K path                       | `environment.moon.phaseName` | image from `lunar_phases`             | 416x240-BWRY               |
+
+<!-- END GENERATED -->
+
+The original single-file version is also still available as `tide.svg`:
+
+<!-- BEGIN GENERATED: template-reference tide.svg -->
+<!-- Generated from the bundled templates by `npm run docs:templates` - do not edit by hand. -->
+
+**Template:** `tide.svg`
+
+| File                                                                                               | Size (px) | Aspect ratio | Colours | Fits these labels exactly |
+| -------------------------------------------------------------------------------------------------- | --------- | ------------ | ------- | ------------------------- |
+| [`tide.svg`](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tide.svg) | 416 × 240 | 1.73 : 1     | -       | Zhsunyco 3.7" BWRY        |
+
+**Data used**
+
+| Source                              | Path                         | Options                               |
+| ----------------------------------- | ---------------------------- | ------------------------------------- |
+| `tides` resource (provider `tides`) | `extremes[n].label`          | -                                     |
+| `tides` resource (provider `tides`) | `extremes[n].level`          | category `depth`                      |
+| `tides` resource (provider `tides`) | `extremes[n].time`           | format `local_time`, format `day_mon` |
+| `tides` resource (provider `tides`) | `station.datums.HAT`         | category `depth`, round 1             |
+| `tides` resource (provider `tides`) | `station.datums.LAT`         | category `depth`, round 1             |
+| `tides` resource (provider `tides`) | `station.name`               | -                                     |
+| `tides` resource (provider `tides`) | `station.source.name`        | -                                     |
+| Plugin                              | `local_zone`                 | -                                     |
+| Plugin                              | `plugin_version`             | -                                     |
+| Plugin                              | `repainted`                  | format `local_datetime_short`         |
+| Signal K path                       | `environment.moon.phaseName` | image from `lunar_phases`             |
+
+<!-- END GENERATED -->

package/docs/examples/watch-schedule.md

@@ -0,0 +1,37 @@
+# Watch Schedule
+
+![Watch Schedule](../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
+
+## Template Reference
+
+<!-- BEGIN GENERATED: template-reference watch -->
+<!-- Generated from the bundled templates by `npm run docs:templates` - do not edit by hand. -->
+
+**Template:** `watch`
+
+| File                                                                                                                           | Size (px) | Aspect ratio | Colours                   | Fits these labels exactly |
+| ------------------------------------------------------------------------------------------------------------------------------ | --------- | ------------ | ------------------------- | ------------------------- |
+| [`watch/416x240-BWRY.svg`](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/watch/416x240-BWRY.svg) | 416 × 240 | 1.73 : 1     | black, white, red, yellow | Zhsunyco 3.7" BWRY        |
+
+**Data used**
+
+| Source        | Path                      | Options                       |
+| ------------- | ------------------------- | ----------------------------- |
+| Plugin        | `plugin_version`          | -                             |
+| Plugin        | `repainted`               | format `local_datetime_short` |
+| Signal K path | `watch.current.endTime`   | format `local_time`           |
+| Signal K path | `watch.current.startTime` | format `local_time`           |
+| Signal K path | `watch.current.teamName`  | -                             |
+| Signal K path | `watch.next.endTime`      | format `local_time`           |
+| Signal K path | `watch.next.startTime`    | format `local_time`           |
+| Signal K path | `watch.next.teamName`     | -                             |
+| Signal K path | `watch.system.name`       | -                             |
+
+<!-- END GENERATED -->

package/docs/extending.md

@@ -0,0 +1,33 @@
+# Extending
+
+## 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
+
+## 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`](templates.md#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 `new esl.Renderer().render()` would for an SVG template. 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. An optional `describeContent(request)` returns a human-readable description of what `render()` will be given (the GenAI plugin returns its fully-substituted LLM prompt); when present, it's logged to the plugin's debug output just before each `render()`, standing in for the `<desc>` bindings an SVG template's debug output would show.
+
+`esl.Renderer` (the SVG renderer), `esl.bitmapToPng`, `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.
+
+## CLI Commands
+
+`esl-cli` can also be extended with new subcommands by a `-r/--require`'d package, which is how [`@rhizomatics/signalk-einklabel-genai-plugin`](templates.md#genai-rendering) adds its own `prompt`/`generate` commands for testing prompts without a device. See [Command Line Interface](cli.md) for the built-in commands.

package/docs/faq.md

@@ -0,0 +1,44 @@
+# 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
+
+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
+
+See [Weak Signal](bluetooth.md#weak-signal).
+
+## 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`](templates.md#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.
+
+## Repaints fail with "Service not available"
+
+If a label connects but every repaint fails a couple of seconds later with `Service not available`, the label itself has most likely got stuck - take its battery out for 10-20 seconds and try again. See [Stuck Labels](bluetooth.md#stuck-labels).
+
+## Bluetooth problems
+
+Choosing an adapter, adapters that stop responding, and Bluetooth starting after SignalK are covered on the [Bluetooth](bluetooth.md) page.

package/docs/getting-started.md

@@ -0,0 +1,111 @@
+# Getting Started
+
+## Pre-requisites
+
+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.
+
+This plugin can reach BLE hardware two ways - pick whichever fits your setup:
+
+- **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 - see [Choosing a Bluetooth Adapter](bluetooth.md#choosing-a-bluetooth-adapter) for 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) - see [Supported Labels](#supported-labels)
+
+5. Correct time zone set on server if local time is to be shown on display
+
+- See [Times are showing incorrectly](faq.md#times-are-showing-incorrectly)
+- 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 - see [Command Line Interface](cli.md).
+
+```bash
+npm install @rhizomatics/signalk-einklabel-plugin
+```
+
+## Configuration
+
+Use the standard configuration option in the SignalK menu for the plugin.
+
+![Plugin Configuration](assets/screenshots/plugin_config.png)
+
+## Setting up a Label
+
+Enable the plugin, and use the large **+** sign to add a label, which opens up these fields.
+
+![Label Config](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 (see [Examples](examples/README.md)), one you've added to the local templates directory, or - if a companion plugin like [`@rhizomatics/signalk-einklabel-genai-plugin`](templates.md#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](templates.md#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](templates.md#reframing)
+- _Compress upload_, _Mirror_ and _Wire format_ - see [Other Image Options](templates.md#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 [Troubleshooting](faq.md#i-cant-see-my-device-as-a-choice-on-the-drop-down-list-after-scan).
+
+## Supported Labels
+
+### 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