CrossEscPos.Abstractions 1.3.0

ESC/POS Receipt Printer Emulator

🖨️ This app emulates a networked receipt printer to test your ESC/POS commands against.

About

• Cross-platform application (Avalonia 12 + SkiaSharp + .NET 10), runs on Windows, macOS and Linux
• Listens for ESC/POS commands over TCP/IP and (optionally) a serial port
• Logs commands and visually represents the resulting receipt(s)
• Renders 1D barcodes and 2D codes (QR, PDF417, DataMatrix, Aztec), bit images, and page mode
• Answers status queries (DLE EOT, GS r, Automatic Status Back) — simulate paper-out, cover, drawer, offline and error states from the Printer state panel
• Signals buzzer / cash-drawer events with a sound and on-screen toast
• Configure the TCP listen address/port and serial port live from the UI
• Export rendered tickets to PNG — all in one image, or one file per cut
• It support different text formattings in the same line, although a few combinations were tested.

Cross-platform fork. This project began as a cross-platform port of roydejong/EscPosEmulator (originally a Windows/WPF app). It has been migrated to Avalonia + SkiaSharp + .NET 10 so it runs on Windows, macOS and Linux, and extended with barcode/QR rendering and a serial transport. All credit for the original emulator goes to the upstream author. See From WPF to Avalonia for before/after screenshots and what the migration took.

👷 This is an unfinished experiment. Use at your own risk and keep your expectations low. 😃

Download

Pre-built, self-contained apps (no .NET install required) are published on the Releases page:

Releases are produced by the Release GitHub Actions workflow on each v* tag.

macOS first launch. The .app is ad-hoc signed but not notarized (no paid Apple Developer ID). macOS quarantines anything downloaded from the internet, so on first launch you may see "CrossEscPos is damaged and can't be opened" (especially on Apple Silicon). Clear the quarantine flag once, then open it:

xattr -dr com.apple.quarantine /path/to/CrossEscPos.app
open /path/to/CrossEscPos.app

(Right-click → Open also works once the quarantine is cleared.)

Built with

• .NET 10 · Avalonia 12 · SkiaSharp (rendering) · CommunityToolkit.Mvvm (MVVM)
• ZXing.Net (1D barcodes) · QRCoder (QR codes) · Ardalis.SmartEnum (class-based enums) · System.IO.Ports (serial)
• ESC-POS-.NET (the Monitor test client) · LibUsbDotNet (direct USB printing)

From WPF to Avalonia: what the migration cost

Entered in the Avalonia Port Challenge. The same write-up is on the project site, next to a live browser demo.

Before: WPF, Windows only	After: Avalonia 12 on macOS
After: Linux	After: browser (WebAssembly)

Starting point

The upstream app (roydejong/EscPosEmulator, last updated July 2025) targeted net9.0-windows7.0 with UseWPF: 48 C#/XAML files, about 2,400 lines. Windows was wired in at four levels:

• Rendering. Every receipt line drew itself with GDI+ (System.Drawing.Bitmap and Graphics), which is Windows-only on .NET 6 and later. The GDI+ types were part of the core interface, IReceiptPrintable.Render(Bitmap, Graphics, int, int). To show a receipt, the window saved each bitmap into a BMP MemoryStream and loaded it back as a WPF BitmapImage.
• UI. Code-behind only. MainWindow.xaml.cs created Image controls by hand, found them again by a GUID-derived Name, and added or removed them from a StackPanel.
• OS calls. A user32!FlashWindow P/Invoke and System.Media.SystemSounds signalled new jobs.
• Assumptions. TCP was the only transport, and the test receipt was read from the current working directory.

The ESC/POS interpreter (one command class per opcode, registered in EscPosInterpreter) had no UI or Windows dependency, so its design carried over unchanged. It is now the headless CrossEscPos.Core package.

What changed, and what each part cost

The numbers

• Time: 7 days with commits over 5 weeks, per the git history. The port and desktop parity landed on June 5–6, 2026 (PRs #1–#7), the layered-package refactor on June 20–21 (#8–#10), and the browser head on July 4–7 (#11–#16).
• Size: from 48 files and ~2.4k lines to 168 files and ~10k lines of C# and AXAML, across 11 projects, 2 samples and 2 test projects. Most of the growth is new features (barcodes, 2D codes, status commands, printer-state simulation, the Monitor, serial/USB, the browser head), not port overhead. The port PR itself (#1) was +2,525 / −487 lines across 60 files.
• Tests: 131 xUnit tests (89 test methods). They run the interpreter against a synthetic render backend, which proves the core is headless, and exercise the controls with Avalonia.Headless.
• Tools: built with AI assistance (Claude Code); the commits carry Co-Authored-By trailers.

What was easy, and what hurt

• Easy: XAML to AXAML, the Fluent theme, Dispatcher.UIThread, and headless UI testing. The UI layer was the smallest part of the port.
• Hurt: removing GDI+. It was part of the core interfaces, not just the view, so the renderer had to be redesigned before anything else could move. After that came per-OS native dependencies (libusb, fontconfig on Linux, macOS signing) and the browser sandbox (no sockets, no raw file system).
• Would do again: put the drawing surface behind an interface first. Once IReceiptCanvas existed, the ImageSharp backend (a community contribution) and the browser head each landed within a few days.

Supported commands

⚠️ Support is currently limited to only a subset of ESC/POS. Even the commands listed here may only be partially implemented.

• Raw Text
• LF: Line feed
• CR: Carriage return
• ESC Commands:
  • Initialize printer (ESC @)
  • Toggle italic (ESC 4 / ESC 5) [possibly deprecated?]
  • Select font (ESC M)
  • Select charset (ESC R)
  • Select character table (ESC t)
  • Select justification (ESC a)
  • Select line spacing (ESC 2 / ESC 3)
  • Toggle emphasis (ESC E)
  • Toggle underline (ESC -)
  • Set print text mode (ESC !)
  • Full cut (ESC m)
  • Partial cut (ESC i)
  • Print and feed n lines (ESC d)
  • Print and feed paper (ESC J)
  • Generate pulse / kick cash drawer (ESC p m t1 t2)
  • Select character code table (ESC t) — PC437/850/852/858/860/863/865/866/1252 remapped to Unicode
  • Beeper (ESC ( A)
  • Bit image (ESC *) — 8-dot and 24-dot inline raster
  • Page mode: select page / standard mode (ESC L / ESC S), print area (ESC W), direction (ESC T), absolute position (ESC $)
  • User-defined characters (ESC & / ESC % / ESC ?) — parsed & stored
• Control characters:
  • Buzzer / beeper (BEL, 0x07)
  • Form feed (FF) — prints the page in page mode
  • Cancel (CAN) — cancels page data
• DLE (real-time) Commands:
  • Real-time status (DLE EOT n, n=1-4)
  • Real-time request / recover (DLE ENQ)
  • Real-time cash-drawer pulse (DLE DC4 1 m t)
• FS Commands:
  • Print stored logo (FS p n m)
  • Auto cut (FS } 0x60 n)
• GS Commands:
  • Select character size
  • Select cut mode and cut paper
  • Paper eject (GS e n [m t])
  • Print raster image (GS v 0 [m xL xH yL yH ...pixels])
  • Print 1D barcode (GS k) — UPC-A/E, EAN-13/8, CODE39, CODE93, CODE128, ITF, CODABAR (both function A & B forms)
  • Set barcode height / module width (GS h / GS w)
  • Select HRI text position / font (GS H / GS f)
  • Print 2D symbols (GS ( k) — QR Code (cn=49), PDF417 (cn=48), DataMatrix (cn=54), Aztec (cn=55)
  • Status / transmit-back: paper & drawer status (GS r), printer ID (GS I), Automatic Status Back (GS a)
  • Download bit image: define (GS *) and print (GS /)
  • Set motion units (GS P), absolute/relative vertical position (GS $ / GS \)
  • Config (accepted/ignored): user setup (GS ( E), print control (GS ( K), response request (GS ( H)

The emulator is bidirectional: status commands (DLE EOT, GS r, GS I) and Automatic Status Back reply to the host over the same TCP/serial connection, driven by the Printer state panel (right side) where you can simulate paper-out/near-end, cover open, cash-drawer open/closed, offline, and error conditions. Like a real device, the emulator refuses to print while it isn't ready (out of paper, cover open, offline, or in an error state) and shows a notification instead.

Barcodes and QR codes render inline on the receipt, with optional HRI text:

Not yet implemented

A few things remain partial or unimplemented:

• Page-mode coordinate system — page mode buffers output and rasterizes it on FF, but absolute/relative positioning (ESC $, GS $, GS \) and print direction (ESC T) are accepted as no-ops rather than fully positioned.
• User-defined glyph substitution — ESC & glyphs are parsed and stored, but the inline text renderer still draws the font glyph rather than the custom bitmap.
• MaxiCode / GS1 DataBar / Composite 2D symbologies (GS ( k cn=50/51/52).
• Graphics commands GS ( L / GS 8 L (NV/raster graphics store-and-print) and other ESC *-family densities.
• Real-time DLE DC4 functions other than the cash-drawer pulse (power-off, recover-and-cancel, buzzer).
• Katakana / CJK code pages render as missing glyphs since the bundled Latin font has no such glyphs.

Contributions welcome — new commands follow the simple BaseCommand pattern in EscPos/Commands and are registered in EscPosInterpreter.RegisterCommands.

Connecting

The emulator accepts ESC/POS data over two transports. Both can be changed live from the UI (left panel): pick a TCP listen address and port and Start/Stop the listener, or select a serial port + baud and Open/Close it (⟳ refreshes the port list). The environment variables below set the initial values at startup:

Examples:

# (run is shorthand for: dotnet run --project src/CrossEscPos.App.Desktop)
dotnet run --project src/CrossEscPos.App.Desktop                  # TCP only, port 9100
ESCPOS_TCP_PORT=9200 dotnet run --project src/CrossEscPos.App.Desktop   # TCP on 9200
ESCPOS_SERIAL_PORT=/dev/ttys004 dotnet run --project src/CrossEscPos.App.Desktop  # TCP 9100 + serial
ESCPOS_TCP_PORT=off ESCPOS_SERIAL_PORT=COM3 dotnet run --project src/CrossEscPos.App.Desktop  # serial only

Pick the render backend (for A/B testing the two rendering libraries) with --backend skia (default) or --backend imagesharp (the managed, no-native backend). The active backend is shown in the window title bar.

dotnet run --project src/CrossEscPos.App.Desktop -- --backend imagesharp   # managed ImageSharp backend
dotnet run --project src/CrossEscPos.App.Desktop -- --backend skia         # default SkiaSharp backend

The status panel shows the active TCP endpoint and serial port.

Testing serial without hardware (app-to-app on one machine)

You don't need a USB serial adapter. Create a virtual serial bridge — a pair of linked ports — then point the emulator at one end and your POS application (or a shell) at the other. Bytes written to one end appear on the other.

macOS / Linux — using socat (brew install socat / apt install socat). A helper script is included:

./scripts/serial-bridge.sh
# It prints a linked pair, e.g.:
#   PORT A (emulator): /dev/ttys004
#   PORT B (your app): /dev/ttys005
# Leave it running.

Then, in two more terminals:

# Terminal 2 — run the emulator on port A
ESCPOS_SERIAL_PORT=/dev/ttys004 dotnet run --project src/CrossEscPos.App.Desktop

# Terminal 3 — send a receipt from "another app" on port B
cat test_receipt.txt > /dev/ttys005
#   …or from your own program, just open /dev/ttys005 like a normal serial port
#   (9600 8N1) and write ESC/POS bytes to it.

The receipt appears in the emulator window. Because the interpreter is stateful across reads, fragmented serial writes (commands split across packets) are handled correctly.

Windows — install com0com and create a linked pair (e.g. COM3 ↔ COM4). Run the emulator with ESCPOS_SERIAL_PORT=COM3 and have your application write to COM4.

Monitor (built-in test client)

Sending test jobs is the monitor's job — the emulator is the device, the monitor is the POS-side client that drives it over the wire (just like a real application would). The Monitor is shared by both heads: click Open monitor… to launch it — a window on desktop, an in-page overlay in the browser. Its test jobs and status display are identical; only the transport differs:

• Desktop (built on ESC-POS-.NET) — pick a transport:
  • TCP/IP — connect to the emulator's listener (or any networked printer).
  • Serial — pick a port + baud; pairs with the emulator's serial transport via a virtual port bridge.
  • USB — print directly to a real USB printer selected from the connected-device list (by VID:PID), via libusb. This is send-only (no status), and needs native libusb installed (macOS brew install libusb, Debian/Ubuntu apt install libusb-1.0-0; bundled on Windows) and the OS not already holding the device.
• Browser — sends over the SignalR proxy (the CrossEscPos.Host hub) to the in-page emulator, for a full round-trip without any native transport.

It then lets you exercise the target without writing any code:

• Print a sample receipt, all 1D barcodes, or QR / PDF417 / DataMatrix / Aztec.
• Send the full feature test receipt, open the cash drawer, buzz, or cut.
• Watch the printer status the emulator reports back: toggle paper-out / cover / drawer / offline in the Printer state panel and the monitor's status display updates live (via Automatic Status Back), confirming the emulator's status responses are wire-correct. When the printer isn't ready, the emulator drops the job and shows a notification, just like real hardware.

Toggling the emulator's Printer state panel pushes status to the monitor in real time — here the printer reports paper low and a recoverable error, so the monitor shows Not ready:

Exporting tickets

Each cut (ESC i / ESC m / GS V) starts a new receipt — a "page". The Export buttons in the left panel save the rendered tickets as PNG:

• Export all (single image) — stacks every receipt into one tall PNG (a save dialog).
• Export each cut (folder) — writes one receipt_NNN.png per cut into a chosen folder.

Architecture & packages

The emulator is split into layered, independently-publishable packages so the rendering backend is swappable and the core runs headless (and in the browser). The namespace is unified under CrossEscPos.* (organized by feature/directory, not by package), so types resolve across assemblies.

Core carries no UI and no graphics-backend dependency, so the library works headless or in WASM. The host (desktop, browser, or your own app) is the composition root: it picks a backend and injects it.

var imageFactory = new SkiaImageFactory();
var typefaces    = new SkiaTypefaceProvider();
var printer      = new ReceiptPrinter(PaperConfiguration.Default, imageFactory, typefaces);
printer.FeedEscPos(escPosBytes);                         // byte[] — ESC/POS is binary
using var image  = printer.CurrentReceipt.Render();      // IReceiptImage
new SkiaImageEncoder().EncodePng(image, outputStream);

📦 Package usage guides: docs/packages/ — getting started, the core emulator, rendering & custom backends (Skia + managed ImageSharp), the Avalonia controls, and the transports. The desktop and browser apps are one shared Avalonia app (src/CrossEscPos.App).

📖 Full reference & guides: the project wiki, including a step-by-step Adding a render backend guide.

Building & running

Requires the .NET 10 SDK (and the wasm-tools workload for the browser head: dotnet workload install wasm-tools).

# Desktop app (Windows / macOS / Linux)
dotnet run --project src/CrossEscPos.App.Desktop

# Headless: ESC/POS bytes -> PNG, no UI, no Avalonia
dotnet run --project samples/CrossEscPos.Headless -- test_receipt.txt out.png

# Browser: the SAME app in the browser (Avalonia WASM head) — full parity with desktop
dotnet run --project src/CrossEscPos.App.Browser

# Web host: serves the browser app AND the SignalR broker on one origin, giving it TCP reception
# (browsers can't open raw sockets). First run publishes the WASM app into wwwroot (cached after).
# Browse to the printed URL; the emulator opens the TCP port itself.
dotnet run --project samples/CrossEscPos.Host

# Tests (unit + headless UI)
dotnet test CrossEscPos.slnx

One app, two heads. The desktop and browser apps are the same Avalonia application (src/CrossEscPos.App) — the same views, view models, receipts, printer-state panel, PNG export, and the Monitor test-client. Only the platform edges differ, injected via IPlatformServices:

A browser can't open a raw TCP listen socket, so the browser head connects over SignalR to samples/CrossEscPos.Host — one ASP.NET Core host that serves the WASM app and runs the broker. The emulator asks the host to open a TCP listener on the address:port you choose; POS software connects there and its jobs bridge to the in-page emulator, with status flowing back. The same hub carries the browser Monitor's jobs, so it round-trips against the in-page emulator too.

• Windows / macOS: no extra setup — native rendering libraries ship with the Avalonia packages.
• Linux: install the usual font/render native deps if they are missing, e.g. sudo apt install libfontconfig1 libfreetype6 (Debian/Ubuntu).

Testing

Two test projects under tests/:

• CrossEscPos.Core.Tests — emulation coverage. ESC/POS sequences are fed through the interpreter and the observable results (rendered draws, printer state, host responses, events) asserted: text and control characters, styling (emphasis/italic/size/justification), cutting and feeding, 1D/2D barcodes and bit images, status/transmit-back (DLE EOT, GS r, GS I, GS a), cash drawer and buzzer, real-time commands, code pages, page mode and not-ready handling — plus exact StatusByteBuilder bit layouts and the SmartEnum code maps. Rendering goes to a synthetic backend, so the suite runs with no SkiaSharp (proving the core is headless).
• CrossEscPos.Controls.Tests — headless Avalonia UI tests for the controls (two-way state binding, receipt image rendering).

dotnet test CrossEscPos.slnx

Fonts & license

Receipt text is rendered with JetBrains Mono, embedded in the CrossEscPos.Rendering.Skia package (under src/CrossEscPos.Rendering.Skia/Assets/Fonts/) so output is identical across platforms and works in the browser sandbox (no file IO). JetBrains Mono is licensed under the SIL Open Font License 1.1; the full license text is included at src/CrossEscPos.Rendering.Skia/Assets/Fonts/OFL.txt. Per the OFL, the font is redistributed here under its original license and "JetBrains Mono" is a trademark of JetBrains s.r.o. To swap in a different monospace font, replace the receipt-mono*.ttf files (and keep its license alongside).

Emulated printer

This program emulates a printer with the following specifications:

• 80mm paper width
• 72mm printing width
• 180x180dpi
• ASCII Font A/B: 12x24 pixels
• Automatic line feed