@rhizomatics/signalk-einklabel-plugin 1.3.0-beta16 → 1.3.0-beta17

package/dist/config.d.ts

@@ -69,6 +69,8 @@ export interface AdvancedDeviceSettings {
      * format. See `CompressionFormat`.
      */
     compressionFormat?: CompressionFormat;
+    /** Send the image without waiting for each write to be acknowledged (zhsunyco) - see `VendorDeviceConfig.writeWithoutResponse`. Unset means off. */
+    writeWithoutResponse?: boolean;
     /** One-shot override to repaint even if the data is unchanged; cleared automatically once that repaint completes. */
     forceRepaint?: boolean;
     /** Per-device override; if omitted, the vendor driver may fall back to a stock/manufacturer-default key. */

package/dist/config.js

@@ -530,6 +530,13 @@ function configSchema(app, discovered = []) {
                                     description: `Chunked needs Compress upload on. Switch back to Auto if the label stops updating. ${docsLink("templates/#other-image-options")}`,
                                     default: "auto",
                                 }),
+                                writeWithoutResponse: {
+                                    type: "boolean",
+                                    title: "Send image without waiting for each write (Zhsunyco)",
+                                    description: "Turn on if a Zhsunyco label fails with ATT error 0x0e when using the SignalK BLE Manager - its writes that " +
+                                        `wait for acknowledgement are rejected by these labels (SignalK 2.33 and earlier). ${docsLink("bluetooth/#zhsunyco-labels-and-the-ble-manager")}`,
+                                    default: false,
+                                },
                                 forceRepaint: {
                                     type: "boolean",
                                     title: "Force repaint",
@@ -628,6 +635,7 @@ function configUiSchema() {
                     compress: MARKDOWN,
                     mirror: { "ui:widget": "radio", ...MARKDOWN },
                     compressionFormat: { "ui:widget": "radio", ...MARKDOWN },
+                    writeWithoutResponse: MARKDOWN,
                     aesKey: { "ui:placeholder": "e.g. 00112233445566778899aabbccddeeff" },
                 },
             },

package/dist/devices/types.d.ts

@@ -83,6 +83,12 @@ export interface VendorDeviceConfig {
     compress?: boolean;
     /** Overrides the model's own wire format - see `CompressionFormat`. Defaults to `"auto"`. */
     compressionFormat?: CompressionFormat;
+    /**
+     * Send the image without waiting for each write to be acknowledged (zhsunyco; ignored otherwise).
+     * Works around SignalK's BLE Manager (2.33 and earlier) sending every acknowledged write as a
+     * "reliable" write, which zhsunyco labels reject with ATT error 0x0e. Defaults to `false`.
+     */
+    writeWithoutResponse?: boolean;
     /**
      * Receives one line per paint step (connecting, connected, uploading, ...), so a paint that stalls
      * shows in the log where it stopped. Omitted means no step logging.

package/dist/devices/zhsunyco/index.js

@@ -13,6 +13,8 @@ const protocol_1 = require("./protocol");
 /** node-ble has no MTU API; this matches the reference driver's mtu(247)-9 default. */
 const UPLOAD_CHUNK_SIZE = 238;
 const CHUNK_WRITE_DELAY_MS = 20;
+/** With nothing acknowledging each write, pace them further apart so the label isn't sent data faster than it can take it. */
+const UNACKNOWLEDGED_CHUNK_WRITE_DELAY_MS = 50;
 const AUTH_SETTLE_DELAY_MS = 500;
 const STATUS_WAIT_TIMEOUT_MS = 60000;
 /** Bounds `readDeviceDetails`' whole connect+read attempt during a scan - see its doc comment. */
@@ -89,14 +91,15 @@ class ZhsunycoDriver {
                 // Upload offsets and the refresh length both count bytes of whatever's actually sent - the
                 // compressed payload when compressing, not the raw buffer it inflates back to.
                 const payload = compress ? (0, compression_1.compressWolinkBlocks)(pixelData) : pixelData;
+                const acknowledged = !config.writeWithoutResponse;
                 log(`uploading ${payload.length} bytes${compress ? ` (compressed from ${pixelData.length})` : ""} in ` +
-                    `${Math.ceil(payload.length / UPLOAD_CHUNK_SIZE)} writes`);
+                    `${Math.ceil(payload.length / UPLOAD_CHUNK_SIZE)} ${acknowledged ? "acknowledged" : "unacknowledged"} writes`);
                 for (let offset = 0; offset < payload.length; offset += UPLOAD_CHUNK_SIZE) {
                     const chunk = payload.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
-                    await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), true);
-                    await (0, bleDiscovery_1.sleep)(CHUNK_WRITE_DELAY_MS);
+                    await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), acknowledged);
+                    await (0, bleDiscovery_1.sleep)(acknowledged ? CHUNK_WRITE_DELAY_MS : UNACKNOWLEDGED_CHUNK_WRITE_DELAY_MS);
                 }
-                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.length), true);
+                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.length), acknowledged);
                 log("refresh sent, waiting for the label to finish");
                 // `Promise.race` can't cancel its loser, so once `statusReceived` settles (the common case)
                 // this timer would otherwise sit alive for the rest of its 60s regardless - see the identical

package/dist/repaintScheduler.js

@@ -375,6 +375,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             mirror: device.advanced?.mirror,
             compress: device.advanced?.compress,
             compressionFormat: device.advanced?.compressionFormat,
+            writeWithoutResponse: device.advanced?.writeWithoutResponse,
             gattBackend,
             log: (message) => app.debug(`${label}: ${message}`),
         });

package/docs/bluetooth.md

@@ -50,6 +50,25 @@ Check for the `bluetooth` service working at both host level and inside the Sign
 
 Sometime Bluetooth adapters, and/or the Linux services that use them, can get into a 'stuck' state, where the only solution is to reboot the server (although unplugging and plugging the dongle may help). The best way to avoid this is using a known good dongle, and using BLE Manager in SignalK wherever possible.
 
+## Zhsunyco Labels and the BLE Manager
+
+With the "Use the SignalK BLE Manager API" setting on, Zhsunyco labels can connect and authenticate, then fail as soon as the image upload starts, with `Operation failed with ATT error: 0x0e` in the log. SignalK's BLE Manager (2.33 and earlier) sends every write that waits for an acknowledgement as a Bluetooth "reliable" write, which these labels don't support.
+
+Either:
+
+- turn on _Send image without waiting for each write (Zhsunyco)_ in the label's _Advanced settings_ - the image is sent with a small gap between writes instead, and the label still confirms once the whole image has arrived; or
+- switch the BLE Manager setting off, if no other plugins need to share Bluetooth with this one.
+
+Gicisky labels aren't affected, since they don't use acknowledged writes.
+
+## Stuck Labels
+
+A label can itself get into a stuck state - usually after several connections were cut off part way through a repaint - where it still advertises and accepts connections, but no longer lists its services. Every repaint then connects and fails a couple of seconds later, with `Service not available` in this plugin's log, or `Characteristic … was not found` from other software such as Home Assistant.
+
+You can confirm it's the label rather than your server: `bluetoothctl info <label address>` shows no `UUID:` lines even after a connection, and the same failure happens from a different adapter or computer.
+
+The fix is to power-cycle the label - take the battery out for 10-20 seconds, put it back, then trigger a repaint (for example with _Force repaint_). If it still fails, the manufacturer's own app may be needed to reset it.
+
 ## Tuning Bluetooth Connections
 
 Labels spend most of their time asleep, so they can be slow to accept a connection, and slow to answer while an image is being sent to them. Linux's Bluetooth defaults are set with phones, headphones and sensors in mind, so if connections to labels regularly time out, or drop partway through a repaint (for example with GATT or connection-abort errors in the log), some Bluetooth settings on the server may need adjusting:

package/docs/faq.md

@@ -35,6 +35,10 @@ Check if the text boxes are normal text or flowed text, and correct to normal te
 
 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.0-beta16",
+  "version": "1.3.0-beta17",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",