escpresso

A virtual ESC/POS thermal receipt printer emulator with real-time GUI preview. Accepts ESC/POS commands over TCP and renders receipts visually, making it useful for POS development, testing, and debugging without a physical printer.

Features

• TCP server on port 9100 (standard POS printer port)
• Real-time GUI preview using egui — see receipts render as data arrives
• 58mm and 80mm paper sizes with switchable UI
• Text formatting — bold, underline, double width/height, inverted, alignment
• Raster graphics — ESC * bit images and GS v 0 raster images
• QR codes via GS ( k
• Code page support — CP437, Windows-1252, and more via encoding_rs
• Print density control (light to dark)
• Paper cut visualization with separator lines
• receiptio compatible — works with the receiptio CLI tool
• 100+ ESC/POS commands parsed (full list)

Installation

From crates.io

cargo install escpresso

Prerequisites (Linux)

• Rust 1.73+ (for div_ceil stabilization)
• System dependencies for egui/eframe:

# Debian/Ubuntu
sudo apt install libgtk-3-dev libxcb-render0-dev libxcb-shape0-dev \
  libxcb-xfixes0-dev libxkbcommon-dev libssl-dev

Build from source

git clone https://github.com/jflaflamme/escpresso.git
cd escpresso
cargo build --release

The binary is at target/release/escpresso.

Usage

Start the emulator

escpresso

A GUI window opens and a TCP server starts on localhost:9100.

Send ESC/POS commands

# Simple text
printf '\x1B\x40Hello World\n\x1B\x69' | nc -w 1 localhost 9100

# Centered bold text
printf '\x1B\x40\x1B\x61\x01\x1B\x45\x01RECEIPT\n\x1B\x45\x00\x1B\x69' | nc -w 1 localhost 9100

Use with receiptio

receiptio converts a simple text format into ESC/POS commands:

npm install -g receiptio

Create a receipt file (receipt.receipt):

{image:https://receiptline.github.io/receiptio/logo.png}
^^^RECEIPT

{border:line}
|Item            |  Price|
|Apple           |  $1.50|
|Orange          |  $2.00|
{border:space}

^^Total: $3.50

{code:https://example.com; option:qrcode,3,L}

{cut}

Send to escpresso:

receiptio -d 192.168.x.x -p 9100 receipt.receipt    # or use localhost
receiptio -o receipt.raw receipt.receipt              # save to file first
cat receipt.raw | nc -w 1 localhost 9100              # then send

Supported Commands

See docs/COMMANDS.md for the complete list with hex codes and implementation status.

Testing

Shell tests

Shell scripts in tests/shell/ send ESC/POS command sequences via netcat:

# Start escpresso first, then in another terminal:
./tests/shell/test_alignment.sh      # Text alignment tests
./tests/shell/test_raster.sh         # Raster image tests
./tests/shell/run_all.sh             # Run all tests

Rust tests

cargo test

Raw file testing

The tests/raw/ directory contains binary ESC/POS captures from various sources:

cat tests/raw/test1_format.raw | nc -w 1 localhost 9100

Code Structure

The codebase is a single src/main.rs with these main components:

• EscPosRenderer — The ESC/POS command parser and state machine. Processes raw bytes into ReceiptElements.
• ReceiptElement — Enum representing rendered items: text lines, raster images, QR codes, separators, paper cuts.
• PrinterState — Tracks current formatting (bold, underline, alignment, density, code page, etc.).
• PaperSize — 58mm or 80mm paper width configuration.
• TCP server — Async Tokio listener that accepts connections and feeds data to the renderer.
• GUI — eframe/egui app that renders ReceiptElements as a scrollable receipt preview.

About

Built by Innolabs — POS integration and Odoo specialists in Cambodia.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Ensure code passes cargo fmt --check and cargo clippy -- -D warnings
4. Add tests if applicable
5. Submit a pull request

License

MIT