@m-scan/device-kit-web

Accès imprimante directement depuis le navigateur, via Web Bluetooth et WebUSB — pour une PWA sur tablette/téléphone, où @m-scan/device-kit-agent (Node.js) ne peut pas tourner. Fait partie du SDK @m-scan/device-kit.

Installation

npm install @m-scan/device-kit-web

Contrainte du navigateur : pas de scan silencieux

Contrairement à NetworkScanner/UsbScanner (agent), Web Bluetooth/WebUSB exigent un clic utilisateur — il n'existe pas de scan() silencieux qui retourne une liste d'appareils. requestDevice() ouvre la boîte de dialogue native du navigateur, où l'utilisateur choisit lui-même l'appareil ; c'est une restriction de sécurité du navigateur, pas une limitation de ce package.

import { requestUsbPrinter, requestBluetoothPrinter } from '@m-scan/device-kit-web'

// Doit être appelé depuis un gestionnaire de clic (geste utilisateur)
button.addEventListener('click', async () => {
  const printer = await requestUsbPrinter() // ouvre le sélecteur USB natif
  await printer.connect()
  await printer.print(bytes) // Uint8Array de commandes ESC/POS
})

button.addEventListener('click', async () => {
  const printer = await requestBluetoothPrinter() // ouvre le sélecteur Bluetooth natif
  await printer.connect()
  await printer.print(bytes)
})

Le générateur ESC/POS (@m-scan/device-kit-escpos) fonctionne tel quel dans un navigateur pour construire bytes — image()/sharp est Node.js uniquement, mais qrCode() (génération depuis texte/URL, sans sharp) fonctionne en navigateur.

Support navigateur

| API | Chrome/Edge (desktop) | Chrome (Android) | Safari (iOS) | Firefox | |---|---|---|---|---| | WebUSB | ✅ | ✅ | ❌ | ❌ | | Web Bluetooth | ✅ | ✅ | ❌ | ❌ |

Nécessite un contexte sécurisé (HTTPS, ou http://localhost en dev). iOS Safari ne supporte ni l'une ni l'autre API (restriction Apple) — aucune solution navigateur n'existe pour iOS ; iOS resterait à couvrir par une app native si nécessaire un jour.

Limitation importante testée : imprimante déjà pilotée par l'OS

Sur Windows, si l'imprimante a déjà un pilote installé (queue d'impression classique — ce qui est le cas courant sur PC), WebUSB échoue à device.open() avec SecurityError: Access denied — testé avec une imprimante USB réelle (Xprinter POS-80, pilote "Generic / Text Only"). C'est le même verrou système que rencontré côté @m-scan/device-kit-usb avec node-usb/claimInterface : l'OS refuse l'accès USB bas niveau à un périphérique déjà revendiqué par un pilote installé, peu importe la bibliothèque utilisée (node-usb, WebUSB — même cause, même blocage).

Sur Android, où une imprimante thermique USB générique n'a généralement aucun pilote OS préinstallé, WebUSB devrait fonctionner normalement — c'est le scénario visé par ce package (PWA sur tablette), pas encore testé sur un vrai appareil Android.

En pratique :

• Poste de caisse PC → utiliser @m-scan/device-kit-agent (queue d'impression du système, contourne ce blocage).
• Tablette/téléphone (PWA) → ce package, en connectant l'imprimante directement sans pilote OS préalable.

API

requestUsbPrinter(options?)

interface RequestUsbPrinterOptions {
  filters?: USBDeviceFilter[] // restreint le sélecteur à des vendorId/productId précis
  interfaceNumber?: number // défaut 0
}

requestBluetoothPrinter(options?)

interface RequestBluetoothPrinterOptions {
  serviceUuid?: string // défaut '000018f0-0000-1000-8000-00805f9b34fb'
  characteristicUuid?: string // défaut '00002af1-0000-1000-8000-00805f9b34fb'
  additionalServiceUuids?: string[]
  chunkSize?: number // défaut 180 — bytes par écriture BLE
}

Les UUID par défaut sont largement utilisés par les imprimantes ESC/POS Bluetooth génériques (marques chinoises courantes), mais pas un standard universel comme SPP l'est pour le Bluetooth classique — vérifier la documentation du modèle précis si la connexion échoue, et passer serviceUuid/characteristicUuid different si besoin.

Statut

WebUsbPrinter/requestUsbPrinter testés avec une imprimante USB réelle (sélection confirmée fonctionnelle ; connexion bloquée par un pilote OS Windows préexistant — voir limitation ci-dessus). WebBluetoothPrinter/ requestBluetoothPrinter pas encore testés avec du matériel réel.

Licence

MIT