node-escpos

The escpos-adapter package allows you to connect to different printer interfaces. You can choose from the following adapter types depending on your hardware connection:

• USB
• Serial
• Bluetooth
• Network
• Console

To use the USB adapter, you must ensure your operating system has the necessary drivers and libraries to support libusb. Failure to do so will result in a LIBUSB_ERROR_NOT_SUPPORTED error when attempting to open devices.

Linux (Ubuntu/Debian)

You must install build-essential and libudev-dev to build libusb:

sudo apt-get install build-essential libudev-dev

Windows

You must use Zadig to install the WinUSB driver for your specific USB device.

The node-escpos library provides several classes to parse and interpret raw byte data returned from an ESC/POS printer regarding its current state. Each class provides a toJSON() method that returns a structured object containing the status of specific hardware components (like the paper sensor, autocutter, or drawer).

Available status classes include:

• PrinterStatus: General printer state (Online/Offline, Drawer status, Paper feed button).
• OfflineCauseStatus: Reasons why the printer might be offline (Cover open, Paper-end, etc.).
• ErrorCauseStatus: Specific error types (Recoverable, Unrecoverable, Autocutter errors).
• RollPaperSensorStatus: Paper levels (Paper near-end, Paper present/not present).

Each status object includes a status field which can be one of: ok, warning, or error.

To use the Printer class, you must provide an Adapter instance (e.g., USB, Network, SerialPort) and a PrinterOptions object. The Printer class manages an internal buffer of ESC/POS commands which are sent to the hardware when flush() is called.

PrinterOptions:

• encoding (string, default: 'GB18030'): The character encoding for text.
• width (number, default: 48): The printable width of the paper.

PrinterModel:

• null: For generic printers.
• 'qsprinter': For specific QSPRIINTER models which may require different command handling.

To use the Screen class, you must provide an existing Adapter instance (such as USB, Network, or SerialPort). You can optionally provide ScreenOptions to specify a character encoding. If no encoding is provided, it defaults to 'GB18030'.

import Screen, { ScreenOptions } from 'escpos-screen';
// Assuming 'adapter' is an instance of an ESCPOS adapter
const options: ScreenOptions = { encoding: 'utf8' };
const screen = new Screen(adapter, options);

The escpos-console package provides a Console handler that outputs ESCPOS commands to the standard output (stdout). This is useful for debugging the raw command sequences being sent to a printer by inspecting them in your terminal.

To use it, require the escpos core library and assign the escpos-console module to escpos.Console. You can then instantiate a new escpos.Console device. By default, it uses stdout as the handler.

const escpos = require('escpos');
escpos.Console = require('escpos-console');

const debugDevice = new escpos.Console();

To connect to an ESCPOS printer via a serial port, you must require both the core escpos package and the escpos-serialport adapter. You can then instantiate a new escpos.SerialPort by providing the port name (e.g., 'COM10' on Windows or a device path like '/dev/usb/lp0' on Linux) and an optional configuration object.

The configuration object supports standard serial port options such as baudRate and stopBit. For a full list of available options, refer to the node-serialport documentation.

const escpos = require('escpos');
escpos.SerialPort = require('escpos-serialport');

// Windows usage
const serialDeviceOnWindows = new escpos.SerialPort('COM10');

// Linux usage with custom options
const serialDeviceOnLinux = new escpos.SerialPort('/dev/usb/lp0', {
  baudRate: 14400,
  stopBit: 2
});

To connect to a USB printer, require the escpos-usb package as escpos.USB and instantiate it using the printer's Vendor ID (vid) and Product ID (pid).

You can find these IDs using the lsusb command on Linux or by calling the escpos.USB.findPrinter() method.

const escpos = require('escpos');
escpos.USB = require('escpos-usb');

const usbDevice = new escpos.USB(0x01, 0xff);

The close(callback) method closes the connection to the current device and releases its interface (such as the USB interface) so that other processes or subsequent calls can use it.

Callback signature: function callback()

To use the escpos-screen functionality, you must pass an existing device instance (USB, Serial, Bluetooth, or Network) into the Screen constructor. This wraps the device to provide screen-specific manipulation methods.

const usbDevice = new escpos.USB();
const usbScreen = new escpos.Screen(usbDevice);

const serialDevice = new escpos.Serial('/dev/ttyUSB0');
const serialScreen = new escpos.Screen(serialDevice);

const bluetoothDevice = new escpos.Bluetooth('01:23:45:67:89:AB', 1);
const bluetoothScreen = new escpos.Screen(bluetoothDevice);

const networkDevice = new escpos.Network('localhost');
const networkScreen = new escpos.Screen(networkDevice);