67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
# 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](https://www.npmjs.com/package/dotenv).
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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. |