@opendisplay/opendisplay 1.0.1 → 1.1.1

package/dist/index.d.cts

@@ -651,7 +651,10 @@ declare class OpenDisplayDevice {
      * await device.uploadImage(imageData, {
      *   refreshMode: RefreshMode.FULL,
      *   ditherMode: DitherMode.BURKES,
-     *   compress: true
+     *   compress: true,
+     *   onProgress: (current, total, stage) => {
+     *     console.log(`${stage}: ${current}/${total} (${Math.floor(current/total*100)}%)`);
+     *   }
      * });
      * ```
      */
@@ -659,6 +662,8 @@ declare class OpenDisplayDevice {
         refreshMode?: RefreshMode;
         ditherMode?: DitherMode;
         compress?: boolean;
+        onProgress?: (current: number, total: number, stage: string) => void;
+        onStatusChange?: (message: string) => void;
     }): Promise<void>;
     /**
      * Execute image upload using compressed or uncompressed protocol.
@@ -673,6 +678,8 @@ declare class OpenDisplayDevice {
      * - Progress logging
      *
      * @param imageData - Data to send in chunks
+     * @param onProgress - Optional progress callback (current bytes, total bytes, stage)
+     * @param onStatusChange - Optional status message callback
      * @returns True if device auto-completed (sent 0x0072 END early), false if all chunks sent normally
      * @throws {ProtocolError} If unexpected response received
      * @throws {BLETimeoutError} If no response within timeout

package/dist/index.d.ts

@@ -651,7 +651,10 @@ declare class OpenDisplayDevice {
      * await device.uploadImage(imageData, {
      *   refreshMode: RefreshMode.FULL,
      *   ditherMode: DitherMode.BURKES,
-     *   compress: true
+     *   compress: true,
+     *   onProgress: (current, total, stage) => {
+     *     console.log(`${stage}: ${current}/${total} (${Math.floor(current/total*100)}%)`);
+     *   }
      * });
      * ```
      */
@@ -659,6 +662,8 @@ declare class OpenDisplayDevice {
         refreshMode?: RefreshMode;
         ditherMode?: DitherMode;
         compress?: boolean;
+        onProgress?: (current: number, total: number, stage: string) => void;
+        onStatusChange?: (message: string) => void;
     }): Promise<void>;
     /**
      * Execute image upload using compressed or uncompressed protocol.
@@ -673,6 +678,8 @@ declare class OpenDisplayDevice {
      * - Progress logging
      *
      * @param imageData - Data to send in chunks
+     * @param onProgress - Optional progress callback (current bytes, total bytes, stage)
+     * @param onStatusChange - Optional status message callback
      * @returns True if device auto-completed (sent 0x0072 END early), false if all chunks sent normally
      * @throws {ProtocolError} If unexpected response received
      * @throws {BLETimeoutError} If no response within timeout

package/dist/index.js

@@ -1340,6 +1340,16 @@ var BLEConnection = class {
     }
     return this.notificationQueue.dequeue(timeoutMs);
   }
+  /**
+   * Clear the notification queue.
+   *
+   * Useful for clearing any stale responses before starting a new operation.
+   * This drains any buffered notifications and cancels pending read requests.
+   */
+  clearQueue() {
+    console.debug(`Clearing notification queue (${this.notificationQueue.size} buffered)`);
+    this.notificationQueue.clear("Queue cleared by request");
+  }
   /**
    * Handle incoming BLE notifications.
    *
@@ -1660,7 +1670,10 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
    * await device.uploadImage(imageData, {
    *   refreshMode: RefreshMode.FULL,
    *   ditherMode: DitherMode.BURKES,
-   *   compress: true
+   *   compress: true,
+   *   onProgress: (current, total, stage) => {
+   *     console.log(`${stage}: ${current}/${total} (${Math.floor(current/total*100)}%)`);
+   *   }
    * });
    * ```
    */
@@ -1670,9 +1683,12 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
     const refreshMode = options.refreshMode ?? 0 /* FULL */;
     const ditherMode = options.ditherMode ?? DitherMode2.BURKES;
     const compress = options.compress ?? true;
+    const onProgress = options.onProgress;
+    const onStatusChange = options.onStatusChange;
     console.log(
       `Uploading image (${this.width}x${this.height}, ${ColorScheme4[this.colorScheme]})`
     );
+    onStatusChange?.("Preparing image...");
     const encodedData = prepareImageForUpload(
       imageData,
       this.width,
@@ -1682,27 +1698,44 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
     );
     let compressedData = null;
     if (compress) {
+      onStatusChange?.("Compressing...");
       compressedData = compressImageData(encodedData, 6);
       if (compressedData.length < MAX_COMPRESSED_SIZE) {
         console.log(`Using compressed upload protocol (size: ${compressedData.length} bytes)`);
+        onStatusChange?.("Uploading...");
         await this.executeUpload({
           imageData: encodedData,
           refreshMode,
           useCompression: true,
           compressedData,
-          uncompressedSize: encodedData.length
+          uncompressedSize: encodedData.length,
+          onProgress,
+          onStatusChange
         });
       } else {
         console.log(
           `Compressed size exceeds ${MAX_COMPRESSED_SIZE} bytes, using uncompressed protocol`
         );
-        await this.executeUpload({ imageData: encodedData, refreshMode });
+        onStatusChange?.("Uploading...");
+        await this.executeUpload({
+          imageData: encodedData,
+          refreshMode,
+          onProgress,
+          onStatusChange
+        });
       }
     } else {
       console.log("Compression disabled, using uncompressed protocol");
-      await this.executeUpload({ imageData: encodedData, refreshMode });
+      onStatusChange?.("Uploading...");
+      await this.executeUpload({
+        imageData: encodedData,
+        refreshMode,
+        onProgress,
+        onStatusChange
+      });
     }
     console.log("Image upload complete");
+    onStatusChange?.("Upload complete!");
   }
   /**
    * Execute image upload using compressed or uncompressed protocol.
@@ -1713,8 +1746,11 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
       refreshMode,
       useCompression = false,
       compressedData,
-      uncompressedSize
+      uncompressedSize,
+      onProgress,
+      onStatusChange
     } = params;
+    this.connection.clearQueue();
     let startCmd;
     let remainingCompressed = null;
     if (useCompression && compressedData && uncompressedSize) {
@@ -1732,11 +1768,12 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
     validateAckResponse(response, 112 /* DIRECT_WRITE_START */);
     let autoCompleted = false;
     if (useCompression && remainingCompressed && remainingCompressed.length > 0) {
-      autoCompleted = await this.sendDataChunks(remainingCompressed);
+      autoCompleted = await this.sendDataChunks(remainingCompressed, onProgress, onStatusChange);
     } else if (!useCompression) {
-      autoCompleted = await this.sendDataChunks(imageData);
+      autoCompleted = await this.sendDataChunks(imageData, onProgress, onStatusChange);
     }
     if (!autoCompleted) {
+      onStatusChange?.("Refreshing display...");
       const endCmd = buildDirectWriteEndCommand(refreshMode);
       await this.connection.writeCommand(endCmd);
       response = await this.connection.readResponse(
@@ -1754,11 +1791,13 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
    * - Progress logging
    *
    * @param imageData - Data to send in chunks
+   * @param onProgress - Optional progress callback (current bytes, total bytes, stage)
+   * @param onStatusChange - Optional status message callback
    * @returns True if device auto-completed (sent 0x0072 END early), false if all chunks sent normally
    * @throws {ProtocolError} If unexpected response received
    * @throws {BLETimeoutError} If no response within timeout
    */
-  async sendDataChunks(imageData) {
+  async sendDataChunks(imageData, onProgress, onStatusChange) {
     let bytesSent = 0;
     let chunksSent = 0;
     while (bytesSent < imageData.length) {
@@ -1779,6 +1818,7 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
           console.log(
             `No response after chunk ${chunksSent} (${(bytesSent / imageData.length * 100).toFixed(1)}%), waiting for device refresh...`
           );
+          onStatusChange?.("Refreshing display...");
           response = await this.connection.readResponse(
             _OpenDisplayDevice.TIMEOUT_REFRESH
           );
@@ -1788,10 +1828,12 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
       }
       const [command, isAck] = checkResponseType(response);
       if (command === 113 /* DIRECT_WRITE_DATA */) {
+        onProgress?.(bytesSent, imageData.length, "upload");
       } else if (command === 114 /* DIRECT_WRITE_END */) {
         console.log(
           `Received END response after chunk ${chunksSent} - device auto-completed`
         );
+        onProgress?.(imageData.length, imageData.length, "upload");
         return true;
       } else {
         throw new ProtocolError(