@tbsoft-gmbh/signature-sdk 1.0.0

package/dist/hid-protocol.d.ts

@@ -0,0 +1,227 @@
+import { DriverConfig } from './types.js';
+
+/**
+ * Low-level HID protocol for Signotec signing pads.
+ *
+ * Handles command framing, register reads/writes, response parsing, and retry logic.
+ * Protocol reverse-engineered from STPadLib.dll (Windows) and libSTPadLib.so (Linux).
+ *
+ * Transport: 63-byte HID output reports, no report ID prefix.
+ * - Register read:  [0x01, register] → response [0x20, register, length, data...]
+ * - Register write: [0x10, register, length, data...] → response [0x20, register, ...]
+ * - Commands:       raw bytes → response first nibble 0x9X for success, 0xE0 for error
+ *
+ * @module hid-protocol
+ */
+
+/** HID command bytes. */
+declare const CMD: {
+    readonly READ_REG: 1;
+    readonly WRITE_REG: 16;
+    readonly START_SIGN: 130;
+    readonly STOP_SIGN: 131;
+    readonly DRAW_IMAGE: 132;
+    readonly IMAGE_DONE: 133;
+    readonly ERASE_DISPLAY: 134;
+    readonly STORE_IMAGE: 137;
+    readonly SHOW_STORED: 138;
+    readonly DATA_CHUNK: 96;
+    readonly STORE_CHUNK: 112;
+    readonly SLIDESHOW_CONFIG: 164;
+    readonly EXTENDED: 168;
+    readonly ADVANCED_BUTTON: 173;
+};
+/** HID response byte types. */
+declare const RESP: {
+    readonly READ: 32;
+    readonly ACK: 144;
+    readonly START_ACK: 146;
+    readonly STOP_ACK: 147;
+    readonly IMAGE_ACK: 148;
+    readonly ERROR: 224;
+    readonly IDLE: 80;
+};
+/** Device register addresses. */
+declare const REG: {
+    readonly DEVICE_ID: 0;
+    readonly FW_VERSION1: 1;
+    readonly FW_VERSION2: 2;
+    readonly STATE: 16;
+    readonly CAPABILITIES: 17;
+    readonly SERIAL: 20;
+    readonly DISPLAY_WIDTH: 21;
+    readonly DISPLAY_HEIGHT: 22;
+    readonly SIGN_LEFT: 50;
+    readonly SIGN_TOP: 51;
+    readonly SIGN_RIGHT: 52;
+    readonly SIGN_BOTTOM: 53;
+};
+/** Signature event types received from the device. */
+declare const SIG_EVENT: {
+    readonly PEN_UP: 64;
+    readonly PEN_DATA: 65;
+    readonly PEN_DATA_EXT: 66;
+    readonly HOTSPOT: 67;
+};
+type HIDDeviceHandle = {
+    on(event: string, callback: (...args: any[]) => void): void;
+    write(data: number[]): void;
+    close(): void;
+    removeAllListeners?(event?: string): void;
+};
+/** Device information read from pad registers. */
+type PadInfo = {
+    serialNo: string;
+    displayWidth: number;
+    displayHeight: number;
+    sensorWidth: number;
+    sensorHeight: number;
+    deviceId: number;
+    fwMajor: number;
+    fwMinor: number;
+    capabilities: number;
+};
+/** Callback for signature/hotspot events from the device. */
+type SignatureEventCallback = (type: number, data: Buffer) => void;
+/**
+ * Low-level HID communication with a Signotec signing pad.
+ *
+ * Provides command framing, response parsing, retry logic, and all
+ * protocol operations (display, signature, flash storage, hotspots).
+ *
+ * @example
+ * ```typescript
+ * const protocol = new HidProtocol({ commandTimeout: 5000 });
+ * const devices = protocol.listDevices();
+ * protocol.open(devices[0].path);
+ * await protocol.eraseDisplay();
+ * protocol.close();
+ * ```
+ */
+declare class HidProtocol {
+    private device;
+    private pending;
+    private signatureCallback;
+    private disconnectCallback;
+    private connected;
+    private closing;
+    private HID;
+    private log;
+    private config;
+    /** Cached USB device descriptors from last listDevices() call (for USB fallback). */
+    private usbDeviceMap;
+    constructor(config?: DriverConfig);
+    /**
+     * Discover all connected Signotec pads.
+     * Tries node-hid first; falls back to raw USB enumeration (libusb) if no
+     * HID devices are found (e.g., Windows without HID class driver).
+     * @returns Array of device descriptors (never throws).
+     */
+    listDevices(): Array<{
+        path: string;
+        serialNumber: string;
+        product: string;
+    }>;
+    /** Log diagnostic info when no devices are found. */
+    private logDiscoveryDiagnostics;
+    /**
+     * Open a device by its path (HID path or USB path).
+     * USB paths start with "usb:" and use the raw USB transport fallback.
+     * @throws Error if the device cannot be opened.
+     */
+    open(devicePath: string): void;
+    /** Close the device connection and release resources. */
+    close(): void;
+    /** Check if the device connection is alive. */
+    isConnected(): boolean;
+    /**
+     * Verify the device is actually responsive (sends a register read and checks response).
+     * Useful after reconnection or before starting a session.
+     */
+    isResponsive(): Promise<boolean>;
+    /** Register a callback for device disconnect events. */
+    onDisconnect(cb: (() => void) | null): void;
+    /** Register a callback for signature/hotspot events from the device. */
+    onSignatureEvent(cb: SignatureEventCallback | null): void;
+    private send;
+    /**
+     * Send a command and wait for the response.
+     * @returns Response buffer, or null on timeout/error.
+     */
+    sendCommand(bytes: number[], timeout?: number): Promise<Buffer | null>;
+    /**
+     * Send a command with automatic retry on failure.
+     * @param bytes Command bytes to send
+     * @param validateFn Function to check if response is valid (defaults to non-null + non-error)
+     * @param timeout Timeout per attempt
+     * @param maxRetries Max retry count (from config if not specified)
+     */
+    sendCommandWithRetry(bytes: number[], validateFn?: (resp: Buffer) => boolean, timeout?: number, maxRetries?: number): Promise<Buffer | null>;
+    /** Send raw bytes without waiting for a response (fire-and-forget). */
+    sendRaw(bytes: number[]): void;
+    /**
+     * Send a bulk data chunk for image transfers.
+     * @param cmdByte Command byte (0x60 for display, 0x70 for flash store)
+     * @param data Source buffer
+     * @param offset Starting offset in data
+     * @param maxPayload Max bytes per chunk (default 62)
+     */
+    private sendChunk;
+    private handleData;
+    /** Read a device register. Returns the data portion or null on error/timeout. */
+    readRegister(reg: number): Promise<Buffer | null>;
+    /** Write a 4-byte little-endian value to a register. */
+    writeRegister(reg: number, value: number): Promise<boolean>;
+    /** Read full device info from registers. */
+    getDeviceInfo(): Promise<PadInfo>;
+    /** Erase the pad display (clear to white). */
+    eraseDisplay(): Promise<boolean>;
+    /**
+     * Send monochrome 1bpp bitmap data to the pad display.
+     * Protocol: 0x84 header → 0x60 data chunks → 0x85 done.
+     * Automatically inverts polarity (pad uses 1=black, framebuffer uses 0=black).
+     */
+    drawImage(x: number, y: number, width: number, height: number, bitmapData: Buffer): Promise<boolean>;
+    /**
+     * Store a 1bpp bitmap to the pad's non-volatile flash as standby image.
+     * Persists across power cycles and USB disconnects.
+     *
+     * Protocol: 0x89 header → 0x70 data chunks → 0xA4 standby config.
+     * Flash uses direct polarity (opposite of display), auto-detected.
+     */
+    storeStandbyImage(width: number, height: number, bitmapData: Buffer): Promise<boolean>;
+    /**
+     * Show the stored standby image from flash on the display.
+     * Command 0x8A = "draw stored image" (from APIClosePad → APIDrawStoredImage).
+     *
+     * Single HID command - no image data transfer. Works regardless of who
+     * stored the image (our library, Signotec SlideShow tool, etc.)
+     */
+    showStandbyFromFlash(): Promise<boolean>;
+    /**
+     * Send a slideshow/standby configuration command (0xA4).
+     * Automatically wraps in 0xA8 for Sigma pads (which don't support direct 0xA4).
+     */
+    private sendSlideshowConfig;
+    /** Set the signature capture rectangle (left, top, width, height → registers 0x32-0x35). */
+    setSignRect(left: number, top: number, width: number, height: number): Promise<boolean>;
+    /** Clear all hotspot areas. */
+    clearHotSpots(): Promise<boolean>;
+    /**
+     * Add a hotspot (touch-sensitive button area).
+     * @param index Hotspot index (0-based)
+     * @param left X position
+     * @param top Y position
+     * @param width Width in pixels
+     * @param height Height in pixels
+     */
+    addHotSpot(index: number, left: number, top: number, width: number, height: number): Promise<boolean>;
+    /** Enable hotspot monitoring (call after addHotSpot). */
+    enableHotspotMonitoring(): Promise<boolean>;
+    /** Start signature capture. Protocol: [0x82, 0x00, 0x00, 0x00, 0x00]. */
+    startSignature(): Promise<boolean>;
+    /** Stop signature capture. */
+    stopSignature(): Promise<boolean>;
+}
+
+export { CMD, type HIDDeviceHandle, HidProtocol, type PadInfo, REG, RESP, SIG_EVENT, type SignatureEventCallback };