node-thermal-printer-js 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# node-thermal-printer-js
+
+Public npm package for sending ESC/POS print jobs to a PSF588 printer over BLE or classic Bluetooth COM port.
+
+## Install
+
+```bash
+npm install node-thermal-printer-js
+```
+
+## Import
+
+```js
+import { printData } from "node-thermal-printer-js";
+
+await printData("Hello from npm!");
+```
+
+## Local Development
+
+This project can print ESC/POS data to PSF588 using either:
+- BLE via Python bridge (`ble_print.py` + `bleak`)
+- Classic Bluetooth Serial (COM port) via `serialport`
+
+## Install Dependencies
+
+```bash
+npm install
+py -3.11 -m pip install -r requirements.txt
+```
+
+## Test Print
+
+### BLE (recommended when no COM port exists)
+
+Default PSF588 setup (auto-detects printer and uses correct characteristic):
+
+```bash
+node test-print.js ble
+```
+
+Or with explicit order ID:
+
+```bash
+node test-print.js ble ORDER123
+```
+
+### BLE with custom device/UUID
+
+```bash
+node test-print.js ble ORDER123 PSF588 "AA:BB:CC:DD:EE:FF" "49535343-8841-43f4-a8d4-ecbe34729bb3"
+```
+
+Args order for BLE:
+1. `ble`
+2. `orderId` (optional)
+3. `bleName` (optional, default: `PSF588`)
+4. `bleAddress` (optional, auto-detected if not provided)
+5. `charUUID` (optional, default: `49535343-8841-43f4-a8d4-ecbe34729bb3` for PSF588)
+
+### Scan for BLE devices
+
+```bash
+node test-print.js scan
+node test-print.js scan PSF588
+```
+
+Output shows all available characteristics and their write permissions.
+
+### COM mode
+
+```bash
+node test-print.js com ORDER123 COM5 9600
+```
+
+## Environment Variables
+
+- `PRINTER_TRANSPORT=ble|com` (default: `ble`)
+- `PRINTER_COM_PORT=COM5` (default: `COM5` for COM mode)
+- `PRINTER_BLE_NAME=PSF588` (default: `PSF588`)
+- `PRINTER_BLE_ADDRESS=AA:BB:CC:DD:EE:FF` (optional, auto-detected)
+- `PRINTER_BLE_CHAR_UUID=49535343-8841-43f4-a8d4-ecbe34729bb3` (default for PSF588)
+- `PRINTER_BLE_CONNECT_TIMEOUT=15` (seconds)
+- `PRINTER_BLE_SCAN_TIMEOUT=10` (seconds)
+- `PRINTER_BLE_PAIR=1` (set to enable OS pairing before connect)
+- `PRINTER_PYTHON_CMD=py` (Python launcher)
+
+## Publish Checklist
+
+Before publishing, make sure the package name is unique on npm and then run:
+
+```bash
+npm pack --dry-run
+npm publish --access public
+```
+
+## PSF588 Printer Info
+
+- **Characteristic for printing:** `49535343-8841-43f4-a8d4-ecbe34729bb3`
+- **Properties:** write-without-response, write
+- **Data format:** ESC/POS (raw binary)
+
+## Troubleshooting
+
+- **"Access Denied" on write:** Characteristic doesn't support writes. Use `node test-print.js scan PSF588` to find a writable one.
+- **Connection timeout:** Keep printer in pairing mode, disconnect from other devices, ensure Bluetooth is enabled on Windows.
+- **Python not found:** Install Python 3.11+ and ensure it's on PATH, or set `PRINTER_PYTHON_CMD=py -3.11`.
+

package/app.js

@@ -0,0 +1,197 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const getEscPosPayload = (data) =>
+  Buffer.concat([
+    Buffer.from([0x1b, 0x40, 0x0a]),
+    Buffer.from(`${data}\n\n\n\n\n`, "utf-8"),
+  ]);
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const bleScriptPath = path.join(scriptDir, "ble_print.py");
+
+const runPythonProcess = ({ cmd, cmdArgs, scriptArgs }) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(cmd, [...cmdArgs, ...scriptArgs], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("error", (err) => {
+      reject(new Error(`Launch error for ${cmd}: ${err.message}`));
+    });
+
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({
+          ok: true,
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          code,
+          cmd,
+          cmdArgs,
+        });
+        return;
+      }
+
+      resolve({
+        ok: false,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        code,
+        cmd,
+        cmdArgs,
+      });
+    });
+  });
+
+const printViaComPort = async (order, options = {}) => {
+  const portPath = options.portPath || process.env.PRINTER_COM_PORT || "COM5";
+  const baudRate = options.baudRate || 9600;
+
+  // Dynamically import `serialport` only when COM transport is requested.
+  let SerialPortModule;
+  try {
+    SerialPortModule = await import("serialport");
+  } catch (e) {
+    return Promise.reject(
+      new Error(`serialport module not available: ${e.message}`),
+    );
+  }
+
+  const SerialPortCtor =
+    SerialPortModule.default || SerialPortModule.SerialPort || SerialPortModule;
+
+  const port = new SerialPortCtor({
+    path: portPath,
+    baudRate,
+    autoOpen: false,
+  });
+
+  return new Promise((resolve, reject) => {
+    port.open((err) => {
+      if (err)
+        return reject(new Error(`Failed to open ${portPath}: ${err.message}`));
+
+      const payload = getEscPosPayload(order);
+
+      port.write(payload, (writeErr) => {
+        if (writeErr) {
+          port.close(() => reject(writeErr));
+          return;
+        }
+
+        port.drain((drainErr) => {
+          port.close(() => {
+            if (drainErr) return reject(drainErr);
+            resolve();
+          });
+        });
+      });
+    });
+  });
+};
+
+const printViaBleBridge = (order, options = {}) => {
+  const payload = getEscPosPayload(order).toString("base64");
+  const args = [
+    bleScriptPath,
+    "--data-b64",
+    payload,
+    "--name",
+    options.bleName || process.env.PRINTER_BLE_NAME || "PSF588",
+  ];
+
+  if (options.bleAddress || process.env.PRINTER_BLE_ADDRESS) {
+    args.push(
+      "--address",
+      options.bleAddress || process.env.PRINTER_BLE_ADDRESS,
+    );
+  }
+
+  if (options.charUUID || process.env.PRINTER_BLE_CHAR_UUID) {
+    args.push(
+      "--char-uuid",
+      options.charUUID || process.env.PRINTER_BLE_CHAR_UUID,
+    );
+  }
+
+  if (options.connectTimeout || process.env.PRINTER_BLE_CONNECT_TIMEOUT) {
+    args.push(
+      "--connect-timeout",
+      String(options.connectTimeout || process.env.PRINTER_BLE_CONNECT_TIMEOUT),
+    );
+  }
+
+  if (options.scanTimeout || process.env.PRINTER_BLE_SCAN_TIMEOUT) {
+    args.push(
+      "--scan-timeout",
+      String(options.scanTimeout || process.env.PRINTER_BLE_SCAN_TIMEOUT),
+    );
+  }
+
+  if (options.pair || process.env.PRINTER_BLE_PAIR === "1") {
+    args.push("--pair");
+  }
+
+  const envCmd = options.pythonCmd || process.env.PRINTER_PYTHON_CMD;
+  const candidates = envCmd
+    ? [{ cmd: envCmd, cmdArgs: [] }]
+    : [
+        { cmd: "py", cmdArgs: ["-3.11"] },
+        { cmd: "py", cmdArgs: ["-3"] },
+        { cmd: "python", cmdArgs: [] },
+      ];
+
+  return new Promise(async (resolve, reject) => {
+    const failures = [];
+
+    for (const candidate of candidates) {
+      // Try multiple launchers because Windows py default can point to a missing runtime.
+      const result = await runPythonProcess({
+        cmd: candidate.cmd,
+        cmdArgs: candidate.cmdArgs,
+        scriptArgs: args,
+      });
+
+      if (result.ok) {
+        resolve(result.stdout);
+        return;
+      }
+
+      failures.push(
+        `${result.cmd} ${result.cmdArgs.join(" ")} -> code ${result.code}: ${result.stderr || result.stdout || "no output"}`,
+      );
+    }
+
+    reject(
+      new Error(
+        `BLE bridge failed for all Python launchers. ${failures.join(" | ")}`,
+      ),
+    );
+  });
+};
+
+// Print to a paired Bluetooth printer exposed as a Windows COM (RFCOMM) port.
+// Preferable on Windows: pair the PSF588 printer in OS Bluetooth settings
+// and note the outgoing COM port (e.g. COM5). Then call `printToPSF588(order, { portPath: 'COM5' })`.
+export const printData = (order, options = {}) => {
+  const transport = options.transport || process.env.PRINTER_TRANSPORT || "ble";
+
+  if (transport === "ble") {
+    return printViaBleBridge(order, options);
+  }
+
+  return printViaComPort(order, options);
+};

package/ble_print.py

@@ -0,0 +1,147 @@
+import argparse
+import asyncio
+import base64
+import sys
+import traceback
+
+from bleak import BleakClient, BleakScanner
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Send ESC/POS bytes to a BLE printer")
+    parser.add_argument("--name", default="PSF588", help="BLE device name contains filter")
+    parser.add_argument("--address", default=None, help="BLE MAC/address to connect directly")
+    parser.add_argument(
+        "--char-uuid",
+        default="49535343-8841-43f4-a8d4-ecbe34729bb3",
+        help="Writable characteristic UUID (default works for PSF588)",
+    )
+    parser.add_argument("--data-b64", required=True, help="Base64 payload bytes")
+    parser.add_argument("--scan-timeout", type=float, default=10.0, help="Scan timeout seconds")
+    parser.add_argument("--connect-timeout", type=float, default=15.0, help="Connect timeout seconds")
+    parser.add_argument("--chunk-size", type=int, default=180, help="Write chunk size")
+    parser.add_argument("--delay-ms", type=int, default=20, help="Delay between chunks in ms")
+    parser.add_argument("--pair", action="store_true", help="Request OS pairing before connect")
+    parser.add_argument("--connect-retries", type=int, default=2, help="Connect retry attempts")
+    return parser.parse_args()
+
+
+async def find_device(name_filter: str, timeout: float):
+    devices = await BleakScanner.discover(timeout=timeout)
+    name_filter = (name_filter or "").lower()
+
+    for device in devices:
+        name = (device.name or "").lower()
+        if name_filter and name_filter in name:
+            return device, device.address, device.name
+
+    return None, None, None
+
+
+def pick_writable_characteristic(services):
+    # Prefer write-without-response characteristics (more reliable for bulk data)
+    candidates = []
+
+    for service in services:
+        for char in service.characteristics:
+            props = set(char.properties)
+            if "write-without-response" in props:
+                candidates.append((char.uuid, False))
+            elif "write" in props:
+                candidates.append((char.uuid, True))
+
+    # Return first write-without-response, then first write
+    for uuid, response_required in candidates:
+        if not response_required:
+            print(f"[DEBUG] Selected write-without-response characteristic: {uuid}")
+            return uuid, response_required
+
+    for uuid, response_required in candidates:
+        print(f"[DEBUG] Selected write characteristic (requires response): {uuid}")
+        return uuid, response_required
+
+    print("[DEBUG] No writable characteristics found")
+    return None, None
+
+
+async def run_print(args):
+    payload = base64.b64decode(args.data_b64)
+
+    address = args.address
+    device = None
+    device_name = args.name
+
+    if not address:
+        device, address, found_name = await find_device(device_name, args.scan_timeout)
+        if not address:
+            raise RuntimeError(
+                f"No BLE device found for name filter '{device_name}'. "
+                "Try setting --address explicitly."
+            )
+        print(f"Found device: {found_name} ({address})")
+
+    target = device if device is not None else address
+
+    last_error = None
+    for attempt in range(1, max(1, args.connect_retries) + 1):
+        try:
+            async with BleakClient(
+                target,
+                timeout=args.connect_timeout,
+                pair=args.pair,
+                winrt={"use_cached_services": False},
+            ) as client:
+                if not client.is_connected:
+                    raise RuntimeError(f"Failed to connect to {address}")
+
+                if hasattr(client, "get_services"):
+                    services = await client.get_services()
+                else:
+                    services = client.services
+
+                char_uuid = args.char_uuid
+                response_required = False
+
+                if not char_uuid:
+                    # Re-scan services fresh and pick writable characteristic
+                    char_uuid, response_required = pick_writable_characteristic(services)
+                    if not char_uuid:
+                        raise RuntimeError("No writable BLE characteristic found on target device")
+
+                print(f"Using characteristic: {char_uuid} (response_required={response_required})")
+
+                chunk_size = max(20, min(args.chunk_size, 512))
+                delay_sec = max(0, args.delay_ms) / 1000.0
+
+                bytes_sent = 0
+                for idx in range(0, len(payload), chunk_size):
+                    chunk = payload[idx : idx + chunk_size]
+                    print(f"[DEBUG] Writing {len(chunk)} bytes to {char_uuid}...")
+                    await client.write_gatt_char(char_uuid, chunk, response=response_required)
+                    bytes_sent += len(chunk)
+                    if delay_sec:
+                        await asyncio.sleep(delay_sec)
+
+                print(f"BLE print sent successfully ({bytes_sent} bytes)")
+                return
+        except Exception as exc:
+            last_error = exc
+            print(f"Connect/write attempt {attempt} failed: {repr(exc)}", file=sys.stderr)
+            if attempt < max(1, args.connect_retries):
+                await asyncio.sleep(1)
+    raise last_error if last_error else RuntimeError("BLE print failed without a specific error")
+
+
+def main():
+    args = parse_args()
+    try:
+        asyncio.run(run_print(args))
+    except Exception as exc:
+        detail = str(exc) or repr(exc)
+        print(f"BLE print failed: {detail}", file=sys.stderr)
+        print(traceback.format_exc(), file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/ble_scan.py

@@ -0,0 +1,72 @@
+import argparse
+import asyncio
+import sys
+
+from bleak import BleakClient, BleakScanner
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Scan BLE devices and list writable characteristics")
+    parser.add_argument("--name-filter", default="", help="Device name contains filter")
+    parser.add_argument("--timeout", type=float, default=10.0, help="Scan timeout seconds")
+    parser.add_argument("--connect-timeout", type=float, default=15.0, help="Connect timeout seconds")
+    return parser.parse_args()
+
+
+async def run_scan(args):
+    print("Scanning for BLE devices...")
+    devices = await BleakScanner.discover(timeout=args.timeout)
+
+    if not devices:
+        print("No BLE devices found.")
+        return
+
+    filtered = [d for d in devices if not args.name_filter or (args.name_filter.lower() in (d.name or "").lower())]
+
+    if not filtered:
+        print(f"No devices matching filter '{args.name_filter}'")
+        return
+
+    print(f"\nFound {len(filtered)} device(s):\n")
+
+    for device in filtered:
+        print(f"Device: {device.name} ({device.address})")
+
+        try:
+            async with BleakClient(device, timeout=args.connect_timeout) as client:
+                if hasattr(client, "get_services"):
+                    services = await client.get_services()
+                else:
+                    services = client.services
+
+                if not services:
+                    print("  No services found")
+                    continue
+
+                for service in services:
+                    print(f"  Service: {service.uuid}")
+
+                    for char in service.characteristics:
+                        props = ", ".join(char.properties)
+                        writable = "write" in char.properties or "write-without-response" in char.properties
+                        marker = " [WRITABLE]" if writable else ""
+                        print(f"    Characteristic: {char.uuid}{marker}")
+                        print(f"      Properties: {props}")
+
+        except Exception as exc:
+            print(f"  Error connecting: {exc}")
+
+        print()
+
+
+def main():
+    args = parse_args()
+    try:
+        asyncio.run(run_scan(args))
+    except Exception as exc:
+        print(f"Scan failed: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "node-thermal-printer-js",
+  "version": "1.0.0",
+  "description": "ESC/POS printer helper for PSF588 Bluetooth and COM printing.",
+  "main": "app.js",
+  "exports": {
+    ".": "./app.js"
+  },
+  "files": [
+    "app.js",
+    "ble_print.py",
+    "ble_scan.py",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node test-api.js",
+    "dev": "node --watch app.js",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "printer",
+    "escpos",
+    "bluetooth",
+    "serialport",
+    "psf588"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "escpos": "^3.0.0-alpha.6",
+    "escpos-serialport": "^3.0.0-alpha.4",
+    "serialport": "^13.0.0"
+  }
+}