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

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 1.3.0
+
+First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services. Off by default until longer term stability demonstrated.
+
 # 1.2.3
 
 - Improved example tide template for 2.9" Gicisky, and added blank and error templates

package/README.md

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

package/dist/cli/index.js

@@ -179,18 +179,18 @@ exports.program
         await (0, bleDiscovery_1.forEachAdvertisedDevice)(adapter, async ({ device, address, name, manufacturerId, manufacturerData }) => {
             const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
             const mfr = manufacturerId !== undefined ? `0x${manufacturerId.toString(16).padStart(4, "0")}` : "";
+            const rssi = await device
+                .getRSSI()
+                .then((value) => (value === undefined ? undefined : Number(value)))
+                .catch(() => undefined);
             if (!driver) {
                 if (opts.allDevices) {
-                    const rssi = await device
-                        .getRSSI()
-                        .then((value) => (value === undefined ? undefined : Number(value)))
-                        .catch(() => undefined);
                     rows.push(["(unmatched)", address, name ?? "", "", "", "", mfr, "", String(rssi ?? "")]);
                 }
                 return;
             }
             matchedCount++;
-            const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData);
+            const found = await driver.identifyDevice({ address, name, manufacturerId, manufacturerData, rssi }, () => (0, bleDiscovery_1.connectWithTimeout)(device, VENDOR_IDENTIFY_TIMEOUT_MS).then(() => (0, bleDiscovery_1.openNodeBleGattConnection)(device)));
             (0, log_1.logDebug)(`${driver.vendor}: identified ${found.name ?? found.address}`);
             const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, "0")}` : "";
             const hwid = found.hwVersion ? `0x${found.hwVersion}` : "";

package/dist/config.d.ts

@@ -75,6 +75,13 @@ export interface PluginConfig {
     scanOnStart: boolean;
     /** How long the startup scan runs, in seconds. */
     scanDurationSeconds: number;
+    /**
+     * Route BLE access through the SignalK server's BLE Manager API (`app.bleApi`, server >= 2.32.0)
+     * instead of connecting to BlueZ directly, so this plugin shares the adapter with other BLE plugins
+     * instead of contending for it - see `bleBackend.ts`. Off by default, and only ever offered in the
+     * config schema when the running server actually has `app.bleApi` (see `configSchema` below).
+     */
+    useBleApi: boolean;
     /** How long to wait for a device to accept a BLE connection before giving up on a repaint attempt, in seconds. */
     paintConnectTimeoutSeconds: number;
     /** How many times to attempt a repaint (including the first try) before giving up and reporting failure. */

package/dist/config.js

@@ -51,6 +51,7 @@ function defaultConfig() {
         templatesDir: "",
         scanOnStart: false,
         scanDurationSeconds: 20,
+        useBleApi: false,
         paintConnectTimeoutSeconds: 30,
         paintRetries: 3,
         settleSeconds: 120,
@@ -61,6 +62,7 @@ const PLUGIN_CONFIG_KEYS = [
     "templatesDir",
     "scanOnStart",
     "scanDurationSeconds",
+    "useBleApi",
     "paintConnectTimeoutSeconds",
     "paintRetries",
     "settleSeconds",
@@ -307,6 +309,18 @@ function configSchema(app, discovered = []) {
     return {
         type: "object",
         properties: {
+            ...(app.bleApi
+                ? {
+                    useBleApi: {
+                        type: "boolean",
+                        title: "Use the SignalK BLE Manager API",
+                        description: "Route Bluetooth access through SignalK server's BLE Manager API (server >= 2.32.0) instead of connecting to " +
+                            "BlueZ directly, so this plugin shares the adapter with other BLE plugins instead of contending for it. Requires " +
+                            "the server to have a local Bluetooth adapter or BLE gateway available (Server → Settings → Bluetooth).",
+                        default: defaults.useBleApi,
+                    },
+                }
+                : {}),
             templatesDir: {
                 type: "string",
                 title: "Templates directory",

package/dist/devices/bleBackend.d.ts

@@ -0,0 +1,20 @@
+import { BLEApi } from "@signalk/server-api";
+import { GattConnection } from "./gattConnection";
+/**
+ * Opens a connection to `address` and (for gicisky) re-scans for a fresh advertisement carrying its
+ * manufacturer data - the two BLE-hardware-access operations a `paint()` needs beyond the
+ * backend-agnostic `GattConnection` a connection itself exposes. `nodeBleBackend()` talks to BlueZ
+ * directly; `bleApiBackend()` routes through the SignalK server's BLE Manager API (`app.bleApi`) so
+ * this plugin shares the adapter with other BLE plugins instead of contending for it - see
+ * `VendorDeviceConfig.gattBackend` in `types.ts` for how a driver picks one.
+ */
+export interface BleBackend {
+    connectGatt(address: string, timeoutMs: number): Promise<GattConnection>;
+    waitForManufacturerData(address: string, manufacturerId: number, timeoutMs: number): Promise<Buffer | undefined>;
+}
+export declare function nodeBleBackend(): BleBackend;
+/**
+ * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
+ * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.
+ */
+export declare function bleApiBackend(bleApi: BLEApi, pluginId: string): BleBackend;

package/dist/devices/bleBackend.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeBleBackend = nodeBleBackend;
+exports.bleApiBackend = bleApiBackend;
+const bleDiscovery_1 = require("./bleDiscovery");
+/** How long to wait for BlueZ to have (or acquire) a `Device` object for the target address before giving up - a separate budget from the connect step itself, matching both drivers' previous hardcoded constant. */
+const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
+function nodeBleBackend() {
+    return {
+        async connectGatt(address, timeoutMs) {
+            const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+            try {
+                const adapter = await bluetooth.defaultAdapter();
+                const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, address, DEVICE_DISCOVERY_TIMEOUT_MS);
+                await (0, bleDiscovery_1.connectWithTimeout)(device, timeoutMs);
+                const conn = (0, bleDiscovery_1.openNodeBleGattConnection)(device);
+                return {
+                    read: conn.read.bind(conn),
+                    write: conn.write.bind(conn),
+                    startNotifications: conn.startNotifications.bind(conn),
+                    stopNotifications: conn.stopNotifications.bind(conn),
+                    discoverServices: conn.discoverServices.bind(conn),
+                    onDisconnect: conn.onDisconnect.bind(conn),
+                    get connected() {
+                        return conn.connected;
+                    },
+                    async disconnect() {
+                        await conn.disconnect();
+                        destroy();
+                    },
+                };
+            }
+            catch (err) {
+                destroy();
+                throw err;
+            }
+        },
+        async waitForManufacturerData(address, manufacturerId, timeoutMs) {
+            const { bluetooth, destroy } = (0, bleDiscovery_1.createBluetooth)();
+            try {
+                const adapter = await bluetooth.defaultAdapter();
+                const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, address, DEVICE_DISCOVERY_TIMEOUT_MS);
+                return await (0, bleDiscovery_1.waitForManufacturerData)(adapter, device, manufacturerId, timeoutMs);
+            }
+            finally {
+                destroy();
+            }
+        },
+    };
+}
+/**
+ * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
+ * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.
+ */
+function bleApiBackend(bleApi, pluginId) {
+    return {
+        async connectGatt(address, timeoutMs) {
+            // A previous ungraceful stop (crash, plugin reload mid-paint) can leave a stale GATT claim
+            // registered under our own pluginId, which would otherwise block this connect with
+            // "already claimed" until the server restarts - see signalk-bluetti-plugin's BleManagerDevice
+            // for the same defensive call. A no-op if we don't currently hold the claim.
+            await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+            const connecting = bleApi.connectGATT(address, pluginId);
+            let timedOut = false;
+            const conn = await Promise.race([connecting, (0, bleDiscovery_1.sleep)(timeoutMs).then(() => void (timedOut = true))]);
+            if (timedOut || !conn) {
+                // The server registers the claim as soon as `connectGATT()` is called, not once it succeeds -
+                // giving up here without releasing it would leave the claim (and, once/if the connect attempt
+                // does eventually land server-side, a live connection) orphaned indefinitely, since this
+                // plugin never gets a handle back to disconnect it itself. `releaseGATTDevice` tears down
+                // whatever the claim currently is, connected or still connecting, regardless of how the
+                // original `connectGATT()` promise eventually settles - disconnecting it too if it does still
+                // resolve afterwards, harmlessly, since a connection the server already released is a no-op to
+                // disconnect again.
+                void bleApi
+                    .releaseGATTDevice(address, pluginId)
+                    .catch(() => { })
+                    .then(() => connecting.then((c) => c.disconnect()).catch(() => { }));
+                throw new Error(`connecting to device timed out after ${timeoutMs}ms`);
+            }
+            return conn;
+        },
+        async waitForManufacturerData(address, manufacturerId, timeoutMs) {
+            // Unlike node-ble's `device.getManufacturerData()`, there's no cached-instant-read path here -
+            // `BLEDeviceInfo` (from `getDevices()`/`getDevice()`) carries mac/name/rssi/seenBy but not
+            // manufacturer data (see `BLEDeviceInfoSchema` in `@signalk/server-api`'s `ble-schemas.ts`) -
+            // only the streamed `BLEAdvertisement` does. So this always actively waits on the stream.
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    unsubscribe();
+                    resolve(undefined);
+                }, timeoutMs);
+                const unsubscribe = bleApi.onAdvertisement(pluginId, (adv) => {
+                    if (adv.mac !== address)
+                        return;
+                    const hex = adv.manufacturerData?.[manufacturerId];
+                    if (hex === undefined)
+                        return;
+                    clearTimeout(timer);
+                    unsubscribe();
+                    resolve(Buffer.from(hex, "hex"));
+                });
+            });
+        },
+    };
+}

package/dist/devices/bleDiscovery.d.ts

@@ -1,4 +1,5 @@
 import { Adapter, Bluetooth, Device } from "@naugehyde/node-ble";
+import { GattConnection } from "./gattConnection";
 export declare function sleep(ms: number): Promise<void>;
 /**
  * Drop-in replacement for `node-ble`'s `createBluetooth` that fails fast and clearly when
@@ -78,3 +79,13 @@ export declare function waitForManufacturerData(adapter: Adapter, device: Device
  * leaving it to retry forever in the background after the thing it was waiting to unblock is gone.
  */
 export declare function waitForAdapter(logDebug: (message: string) => void, cancelled?: () => boolean): Promise<boolean>;
+/**
+ * Adapts an already-connected node-ble `Device` to the `GattConnection` facade device drivers
+ * (`zhsunyco`/`gicisky`) talk to - the same shape `app.bleApi.connectGATT()` returns natively (see
+ * `gattConnection.ts`), so a driver's GATT logic runs unchanged under either backend. node-ble
+ * resolves one `GattCharacteristic` object per (service, characteristic) pair and expects callers to
+ * hold onto it for reads/writes/notifications - this caches that resolution keyed by
+ * `"<serviceUuid>:<charUuid>"` so repeated calls (e.g. one `write` per image chunk) don't re-walk
+ * `device.gatt()` every time.
+ */
+export declare function openNodeBleGattConnection(device: Device): GattConnection;

package/dist/devices/bleDiscovery.js

@@ -10,6 +10,7 @@ exports.connectWithTimeout = connectWithTimeout;
 exports.getOrDiscoverDevice = getOrDiscoverDevice;
 exports.waitForManufacturerData = waitForManufacturerData;
 exports.waitForAdapter = waitForAdapter;
+exports.openNodeBleGattConnection = openNodeBleGattConnection;
 const node_ble_1 = require("@naugehyde/node-ble");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -236,3 +237,91 @@ async function waitForAdapter(logDebug, cancelled = () => false) {
     }
     return false;
 }
+/**
+ * Adapts an already-connected node-ble `Device` to the `GattConnection` facade device drivers
+ * (`zhsunyco`/`gicisky`) talk to - the same shape `app.bleApi.connectGATT()` returns natively (see
+ * `gattConnection.ts`), so a driver's GATT logic runs unchanged under either backend. node-ble
+ * resolves one `GattCharacteristic` object per (service, characteristic) pair and expects callers to
+ * hold onto it for reads/writes/notifications - this caches that resolution keyed by
+ * `"<serviceUuid>:<charUuid>"` so repeated calls (e.g. one `write` per image chunk) don't re-walk
+ * `device.gatt()` every time.
+ */
+function openNodeBleGattConnection(device) {
+    const characteristics = new Map();
+    const notificationListeners = new Map();
+    let gattServer;
+    let connected = true;
+    const key = (serviceUuid, charUuid) => `${serviceUuid}:${charUuid}`;
+    async function resolveCharacteristic(serviceUuid, charUuid) {
+        const cacheKey = key(serviceUuid, charUuid);
+        const cached = characteristics.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+        gattServer ?? (gattServer = device.gatt());
+        const service = await (await gattServer).getPrimaryService(serviceUuid);
+        const characteristic = await service.getCharacteristic(charUuid);
+        characteristics.set(cacheKey, characteristic);
+        return characteristic;
+    }
+    device.on("disconnect", () => {
+        connected = false;
+    });
+    return {
+        async read(serviceUuid, charUuid) {
+            const characteristic = await resolveCharacteristic(serviceUuid, charUuid);
+            return characteristic.readValue();
+        },
+        async write(serviceUuid, charUuid, data, withResponse = true) {
+            const characteristic = await resolveCharacteristic(serviceUuid, charUuid);
+            if (withResponse === false) {
+                await characteristic.writeValueWithoutResponse(data);
+            }
+            else {
+                await characteristic.writeValueWithResponse(data);
+            }
+        },
+        async startNotifications(serviceUuid, charUuid, callback) {
+            const characteristic = await resolveCharacteristic(serviceUuid, charUuid);
+            notificationListeners.set(key(serviceUuid, charUuid), callback);
+            characteristic.on("valuechanged", callback);
+            await characteristic.startNotifications();
+        },
+        async stopNotifications(serviceUuid, charUuid) {
+            const cacheKey = key(serviceUuid, charUuid);
+            const characteristic = characteristics.get(cacheKey);
+            const listener = notificationListeners.get(cacheKey);
+            if (characteristic && listener) {
+                characteristic.removeListener("valuechanged", listener);
+                notificationListeners.delete(cacheKey);
+                await characteristic.stopNotifications().catch(() => { });
+            }
+        },
+        async discoverServices() {
+            gattServer ?? (gattServer = device.gatt());
+            const server = await gattServer;
+            const services = [];
+            for (const serviceUuid of await server.services()) {
+                const service = await server.getPrimaryService(serviceUuid);
+                const characteristicInfos = [];
+                for (const charUuid of await service.characteristics()) {
+                    const characteristic = await service.getCharacteristic(charUuid);
+                    characteristics.set(key(serviceUuid, charUuid), characteristic);
+                    const properties = await characteristic.getFlags().catch(() => []);
+                    characteristicInfos.push({ uuid: charUuid, properties });
+                }
+                services.push({ uuid: serviceUuid, characteristics: characteristicInfos });
+            }
+            return services;
+        },
+        async disconnect() {
+            await device.disconnect();
+        },
+        get connected() {
+            return connected;
+        },
+        onDisconnect(callback) {
+            device.on("disconnect", () => callback());
+        },
+    };
+}

package/dist/devices/discoveryCoordinator.d.ts

@@ -10,10 +10,11 @@ export interface ScanResult {
 /** epoch ms a scan was started at, if one is currently running - `undefined` otherwise. */
 export declare function scanInProgressSince(): number | undefined;
 /**
- * Runs one BLE discovery scan and persists what it finds. node-ble/BlueZ has no scan-cancellation
- * API and can't run two discovery sessions at once, so a caller that arrives while a scan is
- * already running (e.g. the startup scan and an on-demand scan for a `device: "ALL"` repaint both
- * wanting to scan at the same moment) is hooked into that *same* in-flight scan's eventual result
- * instead of starting a second BlueZ session, which would make both fail.
+ * Runs one BLE discovery scan and persists what it finds. Neither backend can run two discovery
+ * sessions at once (node-ble/BlueZ has no scan-cancellation API; the BLE Manager API tracks one
+ * subscription per plugin), so a caller that arrives while a scan is already running (e.g. the
+ * startup scan and an on-demand scan for a `device: "ALL"` repaint both wanting to scan at the same
+ * moment) is hooked into that *same* in-flight scan's eventual result instead of starting a second
+ * one, which would make both fail.
  */
-export declare function ensureScan(app: ServerAPI, durationSeconds: number): Promise<ScanResult>;
+export declare function ensureScan(app: ServerAPI, durationSeconds: number, useBleApi: boolean): Promise<ScanResult>;

package/dist/devices/discoveryCoordinator.js

@@ -3,31 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanInProgressSince = scanInProgressSince;
 exports.ensureScan = ensureScan;
 const bleDiscovery_1 = require("./bleDiscovery");
+const bleBackend_1 = require("./bleBackend");
 const discoveredDevicesStore_1 = require("./discoveredDevicesStore");
 const registry_1 = require("./registry");
+const pluginVersion_1 = require("../pluginVersion");
 let inFlight;
 /** epoch ms a scan was started at, if one is currently running - `undefined` otherwise. */
 function scanInProgressSince() {
     return inFlight?.startedAt;
 }
+/** How long a `connect()` closure built during a scan waits for the GATT connect step itself - a scan may be enumerating several devices, so kept short relative to `paint()`'s own connect timeout. */
+const SCAN_GATT_CONNECT_TIMEOUT_MS = 10000;
 /**
- * Runs one BLE discovery scan and persists what it finds. node-ble/BlueZ has no scan-cancellation
- * API and can't run two discovery sessions at once, so a caller that arrives while a scan is
- * already running (e.g. the startup scan and an on-demand scan for a `device: "ALL"` repaint both
- * wanting to scan at the same moment) is hooked into that *same* in-flight scan's eventual result
- * instead of starting a second BlueZ session, which would make both fail.
+ * Runs one BLE discovery scan and persists what it finds. Neither backend can run two discovery
+ * sessions at once (node-ble/BlueZ has no scan-cancellation API; the BLE Manager API tracks one
+ * subscription per plugin), so a caller that arrives while a scan is already running (e.g. the
+ * startup scan and an on-demand scan for a `device: "ALL"` repaint both wanting to scan at the same
+ * moment) is hooked into that *same* in-flight scan's eventual result instead of starting a second
+ * one, which would make both fail.
  */
-function ensureScan(app, durationSeconds) {
+function ensureScan(app, durationSeconds, useBleApi) {
     if (inFlight) {
         return inFlight.promise;
     }
-    const promise = runScan(app, durationSeconds).finally(() => {
+    const promise = (useBleApi && !!app.bleApi ? runScanViaBleApi(app, durationSeconds) : runScanViaBlueZ(app, durationSeconds)).finally(() => {
         inFlight = undefined;
     });
     inFlight = { startedAt: Date.now(), promise };
     return promise;
 }
-async function runScan(app, durationSeconds) {
+async function runScanViaBlueZ(app, durationSeconds) {
     const foundThisScan = [];
     const drivers = (0, registry_1.allDrivers)();
     try {
@@ -37,7 +42,12 @@ async function runScan(app, durationSeconds) {
                 if (!driver) {
                     return;
                 }
-                const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData).catch((err) => {
+                const rssi = await device
+                    .getRSSI()
+                    .then((value) => (value === undefined ? undefined : Number(value)))
+                    .catch(() => undefined);
+                const connect = () => (0, bleDiscovery_1.connectWithTimeout)(device, SCAN_GATT_CONNECT_TIMEOUT_MS).then(() => (0, bleDiscovery_1.openNodeBleGattConnection)(device));
+                const found = await driver.identifyDevice({ address, name, manufacturerId, manufacturerData, rssi }, connect).catch((err) => {
                     app.debug(`${driver.vendor} scan failed: ${err.message}\n${err.stack ?? ""}`);
                     return undefined;
                 });
@@ -57,3 +67,65 @@ async function runScan(app, durationSeconds) {
     const merged = (0, discoveredDevicesStore_1.recordScanResults)(app, foundThisScan);
     return { foundThisScan, merged };
 }
+/**
+ * Same as `runScanViaBlueZ` but sourced from the SignalK server's BLE Manager API instead of a direct
+ * BlueZ discovery session - subscribes to the merged advertisement stream for `durationSeconds`,
+ * seeded with whatever the server already knows about (mirrors `BleManagerScanner` in
+ * signalk-bluetti-plugin). `app.bleApi.getDevices()`/advertisements don't carry manufacturer data
+ * directly comparable to node-ble's `Buffer` - `adv.manufacturerData` is `Record<number, string>`
+ * (decimal company ID -> hex-encoded payload), converted here so drivers never see the difference.
+ */
+async function runScanViaBleApi(app, durationSeconds) {
+    const foundThisScan = [];
+    const seen = new Set();
+    const drivers = (0, registry_1.allDrivers)();
+    const backend = (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME);
+    const identify = async (mac, name, rssi, manufacturerDataHex) => {
+        if (seen.has(mac)) {
+            return;
+        }
+        const [manufacturerIdKey] = Object.keys(manufacturerDataHex ?? {});
+        const manufacturerId = manufacturerIdKey === undefined ? undefined : Number(manufacturerIdKey);
+        const manufacturerData = manufacturerId === undefined ? undefined : Buffer.from(manufacturerDataHex[manufacturerId], "hex");
+        const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
+        if (!driver) {
+            return;
+        }
+        seen.add(mac);
+        const connect = () => backend.connectGatt(mac, SCAN_GATT_CONNECT_TIMEOUT_MS);
+        const found = await driver.identifyDevice({ address: mac, name, manufacturerId, manufacturerData, rssi }, connect).catch((err) => {
+            app.debug(`${driver.vendor} scan failed: ${err.message}\n${err.stack ?? ""}`);
+            return undefined;
+        });
+        if (!found) {
+            return;
+        }
+        foundThisScan.push(found);
+        const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, "0")}` : "unknown";
+        const hwid = found.hwVersion ?? "unknown";
+        app.debug(`discovered ${driver.vendor} device "${found.name ?? ""}" [${found.address}] pid=${pid} hwid=${hwid}`);
+    };
+    try {
+        const unsubscribe = app.bleApi.onAdvertisement(pluginVersion_1.PLUGIN_NAME, (adv) => {
+            void identify(adv.mac, adv.name, adv.rssi, adv.manufacturerData);
+        });
+        try {
+            const known = await app.bleApi.getDevices();
+            for (const device of known) {
+                // BLEDeviceInfo (from getDevices()) doesn't carry manufacturer data - see `bleBackend.ts`'s
+                // waitForManufacturerData doc comment. A driver that needs it to identify (e.g. gicisky) will
+                // still show up once its advertisement arrives on the stream above during this scan window.
+                await identify(device.mac, device.name, device.rssi, undefined);
+            }
+            await (0, bleDiscovery_1.sleep)(durationSeconds * 1000);
+        }
+        finally {
+            unsubscribe();
+        }
+    }
+    catch (err) {
+        app.debug(`scan failed: ${err.message}\n${err.stack ?? ""}`);
+    }
+    const merged = (0, discoveredDevicesStore_1.recordScanResults)(app, foundThisScan);
+    return { foundThisScan, merged };
+}

package/dist/devices/gattConnection.d.ts

@@ -0,0 +1,9 @@
+import { BLEGattConnection } from "@signalk/server-api";
+/**
+ * Service+characteristic-UUID-keyed GATT surface both BLE backends satisfy - `app.bleApi.connectGATT()`
+ * already returns exactly this shape (it *is* `BLEGattConnection`), and `openNodeBleGattConnection`
+ * (`bleDiscovery.ts`) adapts a node-ble `Device` to it. Device drivers (`zhsunyco`/`gicisky`) talk to
+ * this instead of either BLE library directly, so they work unchanged under whichever backend a caller
+ * hands them - see `bleBackend.ts`.
+ */
+export type GattConnection = BLEGattConnection;

package/dist/devices/gattConnection.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/devices/gicisky/index.d.ts

@@ -1,4 +1,3 @@
-import { Device } from "@naugehyde/node-ble";
 import { Bitmap } from "../../render/types";
 import { DeviceMetadata, DiscoveredDevice, VendorDeviceConfig, VendorDriver } from "../types";
 export declare class GiciskyDriver implements VendorDriver {
@@ -6,6 +5,12 @@ export declare class GiciskyDriver implements VendorDriver {
     matchesAdvertisement(_name: string | undefined, manufacturerId: number | undefined): boolean;
     metadataForPid(pid: number): DeviceMetadata | undefined;
     supportedDevices(): DeviceMetadata[];
-    identifyDevice(device: Device, address: string, name: string | undefined, manufacturerId: number | undefined, manufacturerData: Buffer | undefined): Promise<DiscoveredDevice>;
+    identifyDevice({ address, name, manufacturerId, manufacturerData, rssi, }: {
+        address: string;
+        name: string | undefined;
+        manufacturerId: number | undefined;
+        manufacturerData: Buffer | undefined;
+        rssi: number | undefined;
+    }): Promise<DiscoveredDevice>;
     paint(bitmap: Bitmap, config: VendorDeviceConfig): Promise<void>;
 }