escpos-proxy

Minimal ESC/POS print proxy written as a Node.js ESM app.

It listens for incoming ESC/POS print jobs on a TCP port, forwards the raw bytes straight to a target printer, and automatically parses and renders every job to disk as both a structured .log file and a high-fidelity .png receipt image.

A job is delimited by either:

a cut command ("bladecut") in the stream — ESC/POS GS V = 0x1D 0x56, or
a connection drop (the client closes / resets the connection).

Features

Transparent Proxying: Forwards bytes losslessly to a physical ESC/POS printer.
Advanced Parsing: Decomposes the raw byte stream into ESC/POS commands, tracking formatting states (bold, underline, double-height, alignment).
Native PNG Rendering: Automatically generates a 1-bit style grayscale PNG image of the exact receipt that was printed.
Embedded Graphics: Supports rendering custom embedded IMAGE payloads and generates actual QR codes from ESC Z (2D symbol setup) commands.

Usage

Configuration lives in .env (copy .env.example to .env and edit). It is loaded via dotenv.

cp .env.example .env   # first time only
npm install
npm start

Environment variables (`.env`)

Variable	Default	Description
`LISTEN_HOST`	`0.0.0.0`	Host the proxy listens on
`LISTEN_PORT`	`9100`	Port the proxy listens on
`TARGET_HOST`	`10.10.10.24`	Printer to forward raw bytes to
`TARGET_PORT`	`9100`	Printer port
`LOG_DIR`	`./logs`	Directory for job logs
`CUT_PREFIX`	`1d 56`	ESC/POS cut command prefix, hex space-separated (`GS V`)
`KEEP_AFTER_CUT`	`true`	Treat bytes after a cut as the next job

Real environment variables always take precedence over .env.

Logs and Output

For each completed job, two files are written into LOG_DIR:

job-<timestamp>-<seq>.log — The parsed, human-readable token stream containing command opcodes, parameters, and decoded text.
job-<timestamp>-<seq>.png — A rendered visual receipt using the exact fonts (Font A / Font B) and layout applied by the software.

Testing

The test-send.mjs script sends a sample ESC/POS receipt (with a GS V cut) to the listener so you can verify logging, forwarding, and PNG generation:

# terminal 1
npm start

# terminal 2
npm run test:send

Architecture

The source code resides in the src/ directory:

server.js — The core TCP proxy server and chunk delimiter.
parser.js — The ESC/POS grammar parser.
renderer.js — The PNG generator leveraging the sharp and qrcode libraries to draw the parsed receipt instructions to an image buffer.
font-12x24.js / font-9x16.js — Exported native JS arrays containing the dot-matrix character maps used by the renderer.

3.1 KiB Raw Permalink Blame History