@opendisplay/opendisplay 1.1.4 → 1.2.0

package/README.md

@@ -142,6 +142,54 @@ await device.uploadImage(imageData, {
 });
 ```
 
+### Upload Progress & Callbacks
+
+The `uploadImage()` method supports several optional callbacks for tracking progress and timing:
+
+```typescript
+await device.uploadImage(imageData, {
+  refreshMode: RefreshMode.FULL,
+  ditherMode: DitherMode.BURKES,
+  compress: true,
+
+  // Called during data transfer with progress updates
+  onProgress: (current, total, stage) => {
+    const percent = Math.floor((current / total) * 100);
+    console.log(`${stage}: ${percent}% (${current}/${total} bytes)`);
+  },
+
+  // Called at various stages with status messages
+  onStatusChange: (message) => {
+    console.log(`Status: ${message}`);
+    // Example messages:
+    // - "Preparing image..."
+    // - "Compressing..."
+    // - "Uploading..."
+    // - "Upload complete (X.Xs), refreshing display..."
+    // - "Refresh complete (Y.Ys)"
+  },
+
+  // Called when upload is complete (before display refresh)
+  onUploadComplete: (uploadTimeSeconds) => {
+    console.log(`Upload took ${uploadTimeSeconds.toFixed(1)}s`);
+  },
+
+  // Called when entire operation completes (upload + refresh)
+  onComplete: (uploadTime, refreshTime, totalTime) => {
+    console.log(`Complete! Upload: ${uploadTime.toFixed(1)}s, Refresh: ${refreshTime.toFixed(1)}s, Total: ${totalTime.toFixed(1)}s`);
+  }
+});
+```
+
+**Callback Reference:**
+
+| Callback | Parameters | When Called | Use Case |
+|----------|-----------|-------------|----------|
+| `onProgress` | `(current, total, stage)` | After each data chunk sent | Progress bars, upload percentage |
+| `onStatusChange` | `(message)` | At each operation stage | Status messages, user feedback |
+| `onUploadComplete` | `(uploadTimeSeconds)` | Upload done, before refresh | Track upload performance |
+| `onComplete` | `(uploadTime, refreshTime, totalTime)` | After refresh completes | Final timing summary |
+
 **Supported Refresh Modes:**
 - `RefreshMode.FULL` - Full refresh (recommended, ~15s)
 - `RefreshMode.FAST` - Fast refresh if supported (~2s, may have ghosting)

package/dist/index.cjs

@@ -1744,6 +1744,7 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
     const onProgress = options.onProgress;
     const onStatusChange = options.onStatusChange;
     const onUploadComplete = options.onUploadComplete;
+    const onComplete = options.onComplete;
     console.log(
       `Uploading image (${this.width}x${this.height}, ${import_epaper_dithering4.ColorScheme[this.colorScheme]})`
     );
@@ -1770,7 +1771,8 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
           uncompressedSize: encodedData.length,
           onProgress,
           onStatusChange,
-          onUploadComplete
+          onUploadComplete,
+          onComplete
         });
       } else {
         console.log(
@@ -1782,7 +1784,8 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
           refreshMode,
           onProgress,
           onStatusChange,
-          onUploadComplete
+          onUploadComplete,
+          onComplete
         });
       }
     } else {
@@ -1793,7 +1796,8 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
         refreshMode,
         onProgress,
         onStatusChange,
-        onUploadComplete
+        onUploadComplete,
+        onComplete
       });
     }
     console.log("Image upload complete");
@@ -1811,7 +1815,8 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
       uncompressedSize,
       onProgress,
       onStatusChange,
-      onUploadComplete
+      onUploadComplete,
+      onComplete
     } = params;
     this.connection.clearQueue();
     const uploadStartTime = Date.now();
@@ -1862,6 +1867,7 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
         onStatusChange?.(
           `Refresh complete (${refreshTime.toFixed(1)}s)`
         );
+        onComplete?.(uploadTime, refreshTime, totalTime);
       } else if (responseCode === 116 /* REFRESH_TIMEOUT */) {
         throw new ProtocolError("Display refresh timed out");
       } else {
@@ -1870,10 +1876,34 @@ var OpenDisplayDevice = class _OpenDisplayDevice {
         );
       }
     } else {
-      const totalTime = (Date.now() - uploadStartTime) / 1e3;
-      onUploadComplete?.(totalTime);
-      onStatusChange?.(`Upload and refresh complete (${totalTime.toFixed(1)}s)`);
-      console.log(`Auto-completed in ${totalTime.toFixed(1)}s (upload + refresh)`);
+      const uploadTime = (Date.now() - uploadStartTime) / 1e3;
+      onUploadComplete?.(uploadTime);
+      onStatusChange?.(
+        `Upload complete (${uploadTime.toFixed(1)}s), refreshing display...`
+      );
+      console.log(`Auto-completed upload in ${uploadTime.toFixed(1)}s, waiting for refresh...`);
+      const refreshStartTime = Date.now();
+      const refreshResponse = await this.connection.readResponse(
+        _OpenDisplayDevice.TIMEOUT_REFRESH
+      );
+      const [responseCode] = checkResponseType(refreshResponse);
+      if (responseCode === 115 /* REFRESH_COMPLETE */) {
+        const refreshTime = (Date.now() - refreshStartTime) / 1e3;
+        const totalTime = (Date.now() - uploadStartTime) / 1e3;
+        console.log(
+          `Refresh complete (${refreshTime.toFixed(1)}s), total time: ${totalTime.toFixed(1)}s`
+        );
+        onStatusChange?.(
+          `Refresh complete (${refreshTime.toFixed(1)}s)`
+        );
+        onComplete?.(uploadTime, refreshTime, totalTime);
+      } else if (responseCode === 116 /* REFRESH_TIMEOUT */) {
+        throw new ProtocolError("Display refresh timed out");
+      } else {
+        throw new ProtocolError(
+          `Unexpected refresh response: 0x${responseCode.toString(16).padStart(4, "0")}`
+        );
+      }
     }
   }
   /**